PR Requests, removing thenable, event promise becomes private, next event only allows minecraft signals

Author: optic5471ms

change/@minecraft-gameplay-utilities-8aec48fc-0353-4ce9-81d8-835ede162757.json

@@ -1,6 +1,6 @@
 {
   "type": "major",
-  "comment": "Event promise and thenable added to new gameplay utility library",
+  "comment": "EventPromise and nextEvent() added to gameplay-utilities",
   "packageName": "@minecraft/gameplay-utilities",
   "email": "agriffin@microsoft.com",
   "dependentChangeType": "patch"

libraries/gameplay-utilities/README.md

@@ -2,24 +2,20 @@
 
 A set of utilities and functions for common gameplay operations. Major pieces are covered below.
 
-## Thenable
+## nextEvent() and EventPromise
 
-A promise-like object which allows for cancellation through external resolution with it's `fulfill` and `reject` functions.
-
-## EventThenable
-
-This object provides a "wait for next event" utility. A wrapper around the `Thenable` object which is designed to be used with Minecraft script event signals. Provide the constructor with a signal and it will resolve the promise when the next event for the provided signal is raised. Also provides a `cancel` function to unregister the event and fulfill the promise with `undefined`.
+`nextEvent()` is a function which takes a Minecraft event signal and wraps a promise around the next event being raised. The function returns an `EventPromise` object which is a promise type. When the event is raised, the promise will resolve with the event data, and unsubscribe from the event's signal. The `EventPromise` type also adds a `cancel()` function which will unsubscribe from the event's signal, and fulfill the promise with `undefined`.
 
 ### Can be awaited to receive the event
 
 ```ts
-const event = await new EventThenable(world.afterEvents.buttonPush);
+const event = await nextEvent(world.afterEvents.buttonPush);
 ```
 
 ### Can be used like a promise
 
 ```ts
-new EventThenable(world.afterEvents.leverAction).then(
+await nextEvent(world.afterEvents.leverAction).then(
     (event) => {
         // do something with the event
     }).finally(() => {
@@ -30,7 +26,7 @@ new EventThenable(world.afterEvents.leverAction).then(
 ### Optionally provide filters for the signal and use helper function
 
 ```ts
-const creeperDeathEvent = await waitForNextEvent(world.afterEvents.entityDie, { entityTypes: ['minecraft:creeper'] });
+const creeperDeathEvent = await nextEvent(world.afterEvents.entityDie, { entityTypes: ['minecraft:creeper'] });
 ```
 
 ## How to use @minecraft/gameplay-utilities in your project

libraries/gameplay-utilities/api-report/gameplay-utilities.api.md

@@ -40,7 +40,7 @@ export class Thenable<T> {
 }
 
 // @public
-export function waitForNextEvent<T, U>(signal: EventSignal<T, U>, filter?: U): EventThenable<T, U>;
+export function nextEvent<T, U>(signal: EventSignal<T, U>, filter?: U): EventThenable<T, U>;
 
 // (No @packageDocumentation comment for this package)
 

…ay-utilities/src/events/eventThenable.ts …lay-utilities/src/events/eventPromise.tslibraries/gameplay-utilities/src/events/eventThenable.ts renamed to libraries/gameplay-utilities/src/events/eventPromise.ts libraries/gameplay-utilities/src/events/eventThenable.ts renamed to libraries/gameplay-utilities/src/events/eventPromise.ts

@@ -1,37 +1,43 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-import { Thenable } from '../thenable.js';
+import { world, system } from '@minecraft/server';
 
 /**
- * Interface representing the functions required to subscribe and unsubscribe to events.
- *
+ * A promise wrapper utility which returns a new promise that will resolve when the next
+ * event is raised.
+ * 
  * @public
  */
-export interface EventSignal<T, U> {
-    subscribe(closure: (event: T) => void, filter?: U): (event: T) => void;
-    unsubscribe(closure: (event: T) => void): void;
+export interface EventPromise {
+    /**
+     * Cancels the promise and unsubscribes from the event signal. Cancellation is done
+     * by fulfilling with undefined.
+     * 
+     * @public
+     */
+    cancel(): void;
 }
 
 /**
- * Helper to create a new EventThenable from an event signal.
+ * Helper to create a new EventPromise from an after event signal.
  *
  * @public
  */
-export function waitForNextEvent<T, U>(signal: EventSignal<T, U>, filter?: U) {
-    return new EventThenable(signal, filter);
+export function nextEvent<U>(signal: (typeof world.afterEvents[keyof typeof world.afterEvents]) | (typeof system.afterEvents[keyof typeof system.afterEvents]), filter?: U) : EventPromise {
+    return new EventPromiseImpl(signal, filter);
 }
 
 /**
  * A promise wrapper utility which returns a new promise that will resolve when the next
  * event is raised.
  *
- * @public
+ * @private
  */
-export class EventThenable<T, U = undefined> extends Thenable<T | undefined> {
+class EventPromiseImpl<T, U = undefined> extends Promise<T | undefined> {
     private onCancel?: () => void;
 
-    constructor(signal: EventSignal<T, U>, filter?: U) {
+    constructor(signal: typeof world.afterEvents[keyof typeof world.afterEvents], filter?: U) {
         let cancelFn: (() => void) | undefined = undefined;
         super((resolve, _) => {
             let sub: (event: T) => void;
@@ -61,8 +67,6 @@ export class EventThenable<T, U = undefined> extends Thenable<T | undefined> {
      * Cancels the promise by resolving it with undefined and unsubscribing from the event signal.
      */
     cancel() {
-        if (this.onCancel) {
-            this.onCancel();
-        }
+        this.onCancel?.();
     }
 }

libraries/gameplay-utilities/src/events/eventThenable.test.ts

@@ -1,4 +1,4 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
-export * from './eventThenable.js';
+export * from './eventPromise.js';

libraries/gameplay-utilities/src/events/index.ts

@@ -2,4 +2,3 @@
 // Licensed under the MIT License.
 
 export * from './events/index.js';
-export * from './thenable.js';