@fluidframework/tree 2.10.0 → 2.12.0

package/lib/events/listeners.d.ts

@@ -1,76 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-/**
- * `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];
-};
-/**
- * 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 listener function to run when the event is fired.
-     * @returns A {@link Off | function} which will deregister the listener when called.
-     * Calling the deregistration function more than once will have no effect.
-     *
-     * Listeners may also be deregistered by passing the listener to {@link Listenable.off | off()}.
-     * @remarks Registering the exact same `listener` object for the same event more than once will throw an error.
-     * If registering the same listener for the same event multiple times is desired, consider using a wrapper function for the second subscription.
-     */
-    on<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): Off;
-    /**
-     * Deregister an event listener.
-     * @param eventName - The name of the event.
-     * @param listener - The listener function to remove from the current set of event listeners.
-     * @remarks If `listener` is not currently registered, this method will have no effect.
-     *
-     * Listeners may also be deregistered by calling the {@link Off | deregistration function} returned when they are {@link Listenable.on | registered}.
-     */
-    off<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): void;
-}
-/**
- * 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;
-//# sourceMappingURL=listeners.d.ts.map

package/lib/events/listeners.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../src/events/listeners.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,SAAS,IAAI,SAAS,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,GAAG,KAAK,CAAC;AAE9F;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,MAAM,IAAI;KACxC,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;CACrF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,UAAU,CAAC,UAAU,SAAS,MAAM;IACpD;;;;;;;;;;OAUG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,SAAS,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC;IAEtF;;;;;;;OAOG;IACH,GAAG,CAAC,CAAC,SAAS,MAAM,SAAS,CAAC,UAAU,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;CACxF;AAED;;;;;GAKG;AACH,MAAM,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC"}

package/lib/events/listeners.js

@@ -1,6 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-export {};
-//# sourceMappingURL=listeners.js.map

package/lib/events/listeners.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"listeners.js","sourceRoot":"","sources":["../../src/events/listeners.ts"],"names":[],"mappings":"AAAA;;;GAGG","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * `true` iff the given type is an acceptable shape for a {@link Listeners | event} listener\n * @public\n */\nexport type IsListener<TListener> = TListener extends (...args: any[]) => void ? true : false;\n\n/**\n * Used to specify the kinds of events emitted by a {@link Listenable}.\n *\n * @remarks\n * Any object type is a valid {@link Listeners}, but only the {@link IsListener | event-like} properties of that\n * type will be included.\n *\n * @example\n * ```typescript\n * interface MyEvents {\n *   load: (user: string, data: IUserData) => void;\n *   error: (errorCode: number) => void;\n * }\n * ```\n *\n * @public\n */\nexport type Listeners<T extends object> = {\n\t[P in (string | symbol) & keyof T as IsListener<T[P]> extends true ? P : never]: T[P];\n};\n\n/**\n * An object which allows the registration of listeners so that subscribers can be notified when an event happens.\n * @param TListeners - All the {@link Listeners | events} that this subscribable supports\n *\n * @privateRemarks\n * `EventEmitter` can be used as a base class to implement this via extension.\n * ```ts\n * type MyEventEmitter = IEventEmitter<{\n *   load: (user: string, data: IUserData) => void;\n *   error: (errorCode: number) => void;\n * }>\n * ```\n * {@link createEmitter} can help implement this interface via delegation.\n *\n * @sealed @public\n */\nexport interface Listenable<TListeners extends object> {\n\t/**\n\t * Register an event listener.\n\t * @param eventName - The name of the event.\n\t * @param listener - The listener function to run when the event is fired.\n\t * @returns A {@link Off | function} which will deregister the listener when called.\n\t * Calling the deregistration function more than once will have no effect.\n\t *\n\t * Listeners may also be deregistered by passing the listener to {@link Listenable.off | off()}.\n\t * @remarks Registering the exact same `listener` object for the same event more than once will throw an error.\n\t * If registering the same listener for the same event multiple times is desired, consider using a wrapper function for the second subscription.\n\t */\n\ton<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): Off;\n\n\t/**\n\t * Deregister an event listener.\n\t * @param eventName - The name of the event.\n\t * @param listener - The listener function to remove from the current set of event listeners.\n\t * @remarks If `listener` is not currently registered, this method will have no effect.\n\t *\n\t * Listeners may also be deregistered by calling the {@link Off | deregistration function} returned when they are {@link Listenable.on | registered}.\n\t */\n\toff<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): void;\n}\n\n/**\n * A function that, when called, will deregister an event listener subscription that was previously registered.\n * @remarks\n * It is returned by the {@link Listenable.on | event registration function} when event registration occurs.\n * @public\n */\nexport type Off = () => void;\n"]}

package/lib/feature-libraries/chunked-forest/chunk.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk.d.ts","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/chunk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EAEN,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,sBAAsB,EAE3B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAE5D;;;;GAIG;AACH,MAAM,WAAW,SAAU,SAAQ,gBAAgB;IAClD;;;;OAIG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;;;;;;;OAUG;IACH,MAAM,IAAI,aAAa,CAAC;CACxB;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,QAAuB,CAAC;AAEhD;;GAEG;AACH,eAAO,MAAM,WAAW,EAAE,OAAO,MAA8B,CAAC;AAEhE;;GAEG;AACH,UAAU,SAAS;IAClB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,CAAC,WAAW,CAAC,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAC/C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAMtE;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAc,SAAQ,sBAAsB,EAAE,SAAS;IACvE;;;;OAIG;IACH,WAAW,IAAI,OAAO,CAAC;IAEvB;;;OAGG;IACH,IAAI,IAAI,aAAa,CAAC;CACtB"}

package/lib/feature-libraries/chunked-forest/chunk.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"chunk.js","sourceRoot":"","sources":["../../../src/feature-libraries/chunked-forest/chunk.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,qCAAqC,CAAC;AAE7D,OAAO,EAKN,YAAY,GACZ,MAAM,qBAAqB,CAAC;AA8B7B;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAa,YAAY,CAAC;AAEhD;;GAEG;AACH,MAAM,CAAC,MAAM,WAAW,GAAkB,MAAM,CAAC,aAAa,CAAC,CAAC;AA2BhE;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC9C,MAAM,CACL,MAAM,CAAC,IAAI,qCAA6B,EACxC,KAAK,CAAC,+CAA+C,CACrD,CAAC;IACF,OAAQ,MAAoB,CAAC,WAAW,CAAC,CAAC;AAC3C,CAAC","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils/internal\";\n\nimport {\n\tCursorLocationType,\n\ttype FieldKey,\n\ttype ITreeCursor,\n\ttype ITreeCursorSynchronous,\n\trootFieldKey,\n} from \"../../core/index.js\";\nimport type { ReferenceCounted } from \"../../util/index.js\";\n\n/**\n * Contiguous part of the tree which get stored together in some data format.\n * Copy-on-write, but optimized to be mutated in place when a chunk only has a single user (detected using reference counting).\n * This allows for efficient cloning without major performance overheads for non-cloning scenarios.\n */\nexport interface TreeChunk extends ReferenceCounted {\n\t/**\n\t * The number of nodes at the top level of this chunk.\n\t *\n\t * If this chunk is included in a field, this is the amount this chunk contributes to the length of the field.\n\t */\n\treadonly topLevelLength: number;\n\n\t/**\n\t * Creates a cursor for navigating the content of this chunk.\n\t *\n\t * Starts in \"fields\" mode in a `dummyRoot` field containing the top level nodes.\n\t *\n\t * This cursor does not own a reference to the data:\n\t * it is up to the caller of this function to ensure the cursor is not used after they release their owning ref to this chunk.\n\t *\n\t * TODO: consider starting this in \"fields\" mode above the top level\n\t * which would compose better with utilities for processing sequences of nodes.\n\t */\n\tcursor(): ChunkedCursor;\n}\n\n/**\n * The key used for the field that contains the root of chunks when not parented anywhere.\n *\n * For now this is using the document root key to ease testing/compatibility, but this may change.\n */\nexport const dummyRoot: FieldKey = rootFieldKey;\n\n/**\n * A symbol for extracting a TreeChunk from {@link ITreeCursor}.\n */\nexport const cursorChunk: unique symbol = Symbol(\"cursorChunk\");\n\n/**\n * Cursors can optionally implement this interface, allowing querying them for the chunk they are traversing.\n */\ninterface WithChunk {\n\t/**\n\t * When in nodes mode, if a value is returned, it is a TreeChunk who's top level nodes are the\n\t * chunkLength nodes starting from chunkStart.\n\t *\n\t *\n\t * @remarks\n\t * Note that there may be other tree representations with different chunk APIs and thus different ways to query them.\n\t * The chunkStart and chunkLength values thus to not uniquely apply to the chunks accessed through this field.\n\t *\n\t * TODO:\n\t * This API (including the chunk start and end on ITreeCUrsor) have some issues:\n\t * 1. There are cases where multiple possible chunks could be considered.\n\t * For example, when in a SequenceChunk, it could be returned, or the chunk within it could be.\n\t * 2. When in a location other than the root of a chunk,\n\t * it can't provide information about the containing chunk other than by allocating a new chunk that just represents that field.\n\t *\n\t * As more optimizations get implemented, this API may need to change to better address these issues.\n\t */\n\treadonly [cursorChunk]?: TreeChunk | undefined;\n}\n\n/**\n * See {@link WithChunk}.\n */\nexport function tryGetChunk(cursor: ITreeCursor): undefined | TreeChunk {\n\tassert(\n\t\tcursor.mode === CursorLocationType.Nodes,\n\t\t0x57b /* cursorChunk only accessible in nodes mode */,\n\t);\n\treturn (cursor as WithChunk)[cursorChunk];\n}\n\n/**\n * Cursor for a chunk which can be wrapped by another cursor.\n *\n * @remarks See `BasicChunkCursor` which uses this.\n */\nexport interface ChunkedCursor extends ITreeCursorSynchronous, WithChunk {\n\t/**\n\t * Checks if the cursor is in the top level nodes of the chunk.\n\t *\n\t * @returns true iff cursor is within the root field, including at a node within that field.\n\t */\n\tatChunkRoot(): boolean;\n\n\t/**\n\t * Clones the cursor to produce a new independent cursor.\n\t * Does not add any counted references to any chunks.\n\t */\n\tfork(): ChunkedCursor;\n}\n"]}

package/lib/shared-tree-core/transactionStack.d.ts

@@ -1,29 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import type { RevisionTag } from "../core/index.js";
-/**
- * A helper class that organizes the state needed for managing nesting transactions.
- */
-export declare class TransactionStack {
-    private readonly stack;
-    /**
-     * The number of transactions currently ongoing.
-     */
-    get size(): number;
-    /**
-     * Pushes a new transaction onto the stack. That transaction becomes the current transaction.
-     * @param startRevision - the revision of the latest commit when this transaction begins
-     * @param disposables - an optional collection of disposable data to release after finishing a transaction
-     */
-    push(startRevision: RevisionTag, dispose: () => void): void;
-    /**
-     * Ends the current transaction. Fails if there is currently no ongoing transaction.
-     * @returns The revision that the closed transaction began on.
-     */
-    pop(): {
-        startRevision: RevisionTag;
-    };
-}
-//# sourceMappingURL=transactionStack.d.ts.map

package/lib/shared-tree-core/transactionStack.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"transactionStack.d.ts","sourceRoot":"","sources":["../../src/shared-tree-core/transactionStack.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAGpD;;GAEG;AACH,qBAAa,gBAAgB;IAC5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAGb;IAET;;OAEG;IACH,IAAW,IAAI,IAAI,MAAM,CAExB;IAED;;;;OAIG;IACI,IAAI,CAAC,aAAa,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI;IAIlE;;;OAGG;IACI,GAAG,IAAI;QACb,aAAa,EAAE,WAAW,CAAC;KAC3B;CAKD"}

package/lib/shared-tree-core/transactionStack.js

@@ -1,37 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-import { fail } from "../util/index.js";
-/**
- * A helper class that organizes the state needed for managing nesting transactions.
- */
-export class TransactionStack {
-    constructor() {
-        this.stack = [];
-    }
-    /**
-     * The number of transactions currently ongoing.
-     */
-    get size() {
-        return this.stack.length;
-    }
-    /**
-     * Pushes a new transaction onto the stack. That transaction becomes the current transaction.
-     * @param startRevision - the revision of the latest commit when this transaction begins
-     * @param disposables - an optional collection of disposable data to release after finishing a transaction
-     */
-    push(startRevision, dispose) {
-        this.stack.push({ startRevision, dispose });
-    }
-    /**
-     * Ends the current transaction. Fails if there is currently no ongoing transaction.
-     * @returns The revision that the closed transaction began on.
-     */
-    pop() {
-        const transaction = this.stack.pop() ?? fail("No transaction is currently in progress");
-        transaction.dispose();
-        return transaction;
-    }
-}
-//# sourceMappingURL=transactionStack.js.map

package/lib/shared-tree-core/transactionStack.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"transactionStack.js","sourceRoot":"","sources":["../../src/shared-tree-core/transactionStack.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAExC;;GAEG;AACH,MAAM,OAAO,gBAAgB;IAA7B;QACkB,UAAK,GAGhB,EAAE,CAAC;IA6BV,CAAC;IA3BA;;OAEG;IACH,IAAW,IAAI;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACI,IAAI,CAAC,aAA0B,EAAE,OAAmB;QAC1D,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACI,GAAG;QAGT,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,yCAAyC,CAAC,CAAC;QACxF,WAAW,CAAC,OAAO,EAAE,CAAC;QACtB,OAAO,WAAW,CAAC;IACpB,CAAC;CACD","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport type { RevisionTag } from \"../core/index.js\";\nimport { fail } from \"../util/index.js\";\n\n/**\n * A helper class that organizes the state needed for managing nesting transactions.\n */\nexport class TransactionStack {\n\tprivate readonly stack: {\n\t\tstartRevision: RevisionTag;\n\t\tdispose: () => void;\n\t}[] = [];\n\n\t/**\n\t * The number of transactions currently ongoing.\n\t */\n\tpublic get size(): number {\n\t\treturn this.stack.length;\n\t}\n\n\t/**\n\t * Pushes a new transaction onto the stack. That transaction becomes the current transaction.\n\t * @param startRevision - the revision of the latest commit when this transaction begins\n\t * @param disposables - an optional collection of disposable data to release after finishing a transaction\n\t */\n\tpublic push(startRevision: RevisionTag, dispose: () => void): void {\n\t\tthis.stack.push({ startRevision, dispose });\n\t}\n\n\t/**\n\t * Ends the current transaction. Fails if there is currently no ongoing transaction.\n\t * @returns The revision that the closed transaction began on.\n\t */\n\tpublic pop(): {\n\t\tstartRevision: RevisionTag;\n\t} {\n\t\tconst transaction = this.stack.pop() ?? fail(\"No transaction is currently in progress\");\n\t\ttransaction.dispose();\n\t\treturn transaction;\n\t}\n}\n"]}

package/lib/util/transactionResult.d.ts

@@ -1,19 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-/**
- * Describes the result of a transaction.
- * Transactions may either succeed and commit, or fail and abort.
- */
-export declare enum TransactionResult {
-    /**
-     * Indicates the transaction failed.
-     */
-    Abort = 0,
-    /**
-     * Indicates the transaction succeeded.
-     */
-    Commit = 1
-}
-//# sourceMappingURL=transactionResult.d.ts.map

package/lib/util/transactionResult.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"transactionResult.d.ts","sourceRoot":"","sources":["../../src/util/transactionResult.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,oBAAY,iBAAiB;IAC5B;;OAEG;IACH,KAAK,IAAA;IACL;;OAEG;IACH,MAAM,IAAA;CACN"}

package/lib/util/transactionResult.js

@@ -1,20 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-/**
- * Describes the result of a transaction.
- * Transactions may either succeed and commit, or fail and abort.
- */
-export var TransactionResult;
-(function (TransactionResult) {
-    /**
-     * Indicates the transaction failed.
-     */
-    TransactionResult[TransactionResult["Abort"] = 0] = "Abort";
-    /**
-     * Indicates the transaction succeeded.
-     */
-    TransactionResult[TransactionResult["Commit"] = 1] = "Commit";
-})(TransactionResult || (TransactionResult = {}));
-//# sourceMappingURL=transactionResult.js.map

package/lib/util/transactionResult.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"transactionResult.js","sourceRoot":"","sources":["../../src/util/transactionResult.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AACH,MAAM,CAAN,IAAY,iBASX;AATD,WAAY,iBAAiB;IAC5B;;OAEG;IACH,2DAAK,CAAA;IACL;;OAEG;IACH,6DAAM,CAAA;AACP,CAAC,EATW,iBAAiB,KAAjB,iBAAiB,QAS5B","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\n/**\n * Describes the result of a transaction.\n * Transactions may either succeed and commit, or fail and abort.\n */\nexport enum TransactionResult {\n\t/**\n\t * Indicates the transaction failed.\n\t */\n\tAbort,\n\t/**\n\t * Indicates the transaction succeeded.\n\t */\n\tCommit,\n}\n"]}

package/src/events/README.md

@@ -1,3 +0,0 @@
-# events
-
-This module contains interfaces and helpers for objects that emit and subscribe to events.

package/src/events/emitter.ts

@@ -1,256 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-import { UsageError } from "@fluidframework/telemetry-utils/internal";
-import { getOrCreate } 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.
- */
-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 class EventEmitter<TListeners extends Listeners<TListeners>>
-	implements Listenable<TListeners>, HasListeners<TListeners>
-{
-	protected readonly listeners = new Map<
-		keyof TListeners,
-		Set<(...args: any[]) => TListeners[keyof TListeners]>
-	>();
-
-	// 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.
-	protected constructor(private readonly noListeners?: NoListenersCallback<TListeners>) {}
-
-	protected emit<K extends keyof TListeners>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): void {
-		const listeners = this.listeners.get(eventName);
-		if (listeners !== undefined) {
-			// 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.
-			for (const listener of [...listeners]) {
-				// If listener has been unsubscribed while invoking other listeners, skip it.
-				if (listeners.has(listener)) {
-					listener(...argArray);
-				}
-			}
-		}
-	}
-
-	protected emitAndCollect<K extends keyof TListeners>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): ReturnType<TListeners[K]>[] {
-		const listeners = this.listeners.get(eventName);
-		if (listeners !== undefined) {
-			const argArray: unknown[] = args;
-			const resultArray: ReturnType<TListeners[K]>[] = [];
-			for (const listener of [...listeners.values()]) {
-				resultArray.push(listener(...argArray));
-			}
-			return resultArray;
-		}
-		return [];
-	}
-
-	public on<K extends keyof Listeners<TListeners>>(
-		eventName: K,
-		listener: TListeners[K],
-	): Off {
-		const listeners = getOrCreate(this.listeners, eventName, () => new Set());
-		if (listeners.has(listener)) {
-			const eventDescription =
-				typeof eventName === "symbol" ? eventName.description : String(eventName.toString());
-
-			throw new UsageError(
-				`Attempted to register the same listener object twice for event ${eventDescription}`,
-			);
-		}
-		listeners.add(listener);
-		return () => this.off(eventName, listener);
-	}
-
-	public off<K extends keyof Listeners<TListeners>>(
-		eventName: K,
-		listener: TListeners[K],
-	): void {
-		const listeners = this.listeners.get(eventName);
-		if (listeners?.delete(listener) === true && listeners.size === 0) {
-			this.listeners.delete(eventName);
-			this.noListeners?.(eventName);
-		}
-	}
-
-	public hasListeners(eventName?: keyof TListeners): boolean {
-		if (eventName === undefined) {
-			return this.listeners.size !== 0;
-		}
-		return this.listeners.has(eventName);
-	}
-}
-
-/**
- * This class exposes the constructor and the `emit` method of `EventEmitter`, elevating them from protected to public
- */
-class ComposableEventEmitter<TListeners extends Listeners<TListeners>>
-	extends EventEmitter<TListeners>
-	implements IEmitter<TListeners>
-{
-	public constructor(noListeners?: NoListenersCallback<TListeners>) {
-		super(noListeners);
-	}
-
-	public override emit<K extends keyof TListeners>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): void {
-		return super.emit(eventName, ...args);
-	}
-
-	public override emitAndCollect<K extends keyof TListeners>(
-		eventName: K,
-		...args: Parameters<TListeners[K]>
-	): ReturnType<TListeners[K]>[] {
-		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);
- * 	}
- * }
- * ```
- */
-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

@@ -1,19 +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";

package/src/events/interop.ts

@@ -1,38 +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";
-
-// TODO: this file is currently unused. Use it or remove it.
-
-/**
- * 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;

package/src/events/listeners.ts

@@ -1,80 +0,0 @@
-/*!
- * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
- * Licensed under the MIT License.
- */
-
-/**
- * `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];
-};
-
-/**
- * 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 listener function to run when the event is fired.
-	 * @returns A {@link Off | function} which will deregister the listener when called.
-	 * Calling the deregistration function more than once will have no effect.
-	 *
-	 * Listeners may also be deregistered by passing the listener to {@link Listenable.off | off()}.
-	 * @remarks Registering the exact same `listener` object for the same event more than once will throw an error.
-	 * If registering the same listener for the same event multiple times is desired, consider using a wrapper function for the second subscription.
-	 */
-	on<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): Off;
-
-	/**
-	 * Deregister an event listener.
-	 * @param eventName - The name of the event.
-	 * @param listener - The listener function to remove from the current set of event listeners.
-	 * @remarks If `listener` is not currently registered, this method will have no effect.
-	 *
-	 * Listeners may also be deregistered by calling the {@link Off | deregistration function} returned when they are {@link Listenable.on | registered}.
-	 */
-	off<K extends keyof Listeners<TListeners>>(eventName: K, listener: TListeners[K]): void;
-}
-
-/**
- * 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;