@byloth/core 2.1.4 → 2.1.6

package/src/models/iterators/smart-iterator.ts

@@ -893,7 +893,7 @@ export default class SmartIterator<T, R = void, N = undefined> implements Iterat
      *
      * for (const value of iterator)
      * {
-     *     if (value > 5) { break; } // Closing the iterator...
+     *     if (value > 5) { break; } // "Closing the iterator..."
      *
      *     console.log(value); // 1, 2, 3, 4, 5
      * }

package/src/models/promises/index.ts

@@ -1,5 +1,6 @@
 import DeferredPromise from "./deferred-promise.js";
+import PromiseQueue from "./promise-queue.js";
 import SmartPromise from "./smart-promise.js";
 import TimedPromise from "./timed-promise.js";
 
-export { DeferredPromise, SmartPromise, TimedPromise };
+export { DeferredPromise, PromiseQueue, SmartPromise, TimedPromise };

package/src/models/promises/promise-queue.ts

@@ -0,0 +1,222 @@
+import type { Callback } from "../callbacks/types.js";
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { TimeoutException, ValueException } from "../exceptions/index.js";
+
+import DeferredPromise from "./deferred-promise.js";
+import SmartPromise from "./smart-promise.js";
+import TimedPromise from "./timed-promise.js";
+import type { MaybePromise, PromiseRejecter, PromiseResolver } from "./types.js";
+
+/**
+ * A class that represents a queue of asynchronous operations, allowing them to be executed sequentially.
+ *
+ * It extends the {@link SmartPromise} class, providing a way to manage multiple promises in a controlled manner.   
+ * This class is useful for scenarios where you need to ensure
+ * that only one asynchronous operation is executed at a time,
+ * such as when dealing with API requests, file operations or any other
+ * asynchronous tasks that need to be handled in a specific order.
+ *
+ * ---
+ *
+ * @example
+ * ```ts
+ * const queue = new PromiseQueue();
+ *
+ * queue.enqueue(() => new Promise((resolve) => setTimeout(() => resolve("First"), 2000)))
+ * queue.enqueue(() => new Promise((resolve) => setTimeout(() => resolve("Second"), 500)))
+ * queue.enqueue(() => new Promise((resolve) => setTimeout(() => resolve("Third"), 1000)))
+ *
+ * await queue; // "First", "Second", "Third"
+ * ```
+ */
+export default class PromiseQueue extends SmartPromise<void>
+{
+    /**
+     * The number of promises currently in the queue.
+     */
+    protected _count: number;
+
+    /**
+     * A flag indicating whether the promise is still pending or not.
+     */
+    public override get isPending(): boolean
+    {
+        return this._count > 0;
+    }
+    /**
+     * A flag indicating whether the promise has been fulfilled or not.
+     */
+    public override get isFulfilled(): boolean
+    {
+        return this._count === 0;
+    }
+
+    /**
+     * A flag indicating whether the promise has been rejected or not.
+     *
+     * Please note the {@link PromiseQueue} doesn't support rejection states.  
+     * Accessing this property will always result in a {@link ValueException}.
+     */
+    public override get isRejected(): never
+    {
+        throw new ValueException("`PromiseQueue` doesn't support rejection states.");
+    }
+
+    /**
+     * The native {@link Promise} object wrapped by this instance.
+     */
+    declare protected _promise: Promise<void>;
+
+    /**
+     * Initializes a new instance of the {@link PromiseQueue} class.
+     */
+    public constructor()
+    {
+        super((resolve) => resolve());
+
+        this._count = 0;
+
+        this._isPending = false;
+        this._isFulfilled = false;
+        this._isRejected = false;
+    }
+
+    /**
+     * Enqueues a {@link DeferredPromise} into the queue.
+     *
+     * The promise will be executed in sequence after previously enqueued promises.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const queue = new PromiseQueue();
+     * const deferred = new DeferredPromise(() => console.log("Hello, world!"));
+     * 
+     * queue.enqueue(deferred); // "Hello, world!"
+     * ```
+     *
+     * ---
+     *
+     * @template T The type of value the promise will eventually resolve to.
+     *
+     * @param promise A `DeferredPromise<void, T>` instance to enqueue.
+     *
+     * @returns A {@link Promise} that resolves to the value of the enqueued promise.
+     */
+    public enqueue<T>(promise: DeferredPromise<void, T>): Promise<T>;
+
+    /**
+     * Enqueues a {@link DeferredPromise} into the queue with an optional timeout.
+     *
+     * The promise will be executed in sequence after previously enqueued promises.  
+     * If the promise takes longer than the specified timeout, it will be rejected with a {@link TimeoutException}.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const queue = new PromiseQueue();
+     * const deferred = new DeferredPromise(() => console.log("Hello, world!"));
+     *
+     * queue.enqueue(deferred, 5000); // "Hello, world!"
+     * ```
+     *
+     * ---
+     *
+     * @template T The type of value the promise will eventually resolve to.
+     *
+     * @param promise A `DeferredPromise<void, T>` instance to enqueue.
+     * @param timeout The maximum time in milliseconds that the operation can take before timing out.
+     *
+     * @returns
+     * A {@link TimedPromise} that resolves to the value of the enqueued promise or rejects
+     * with a `TimeoutException` if the operation takes longer than the specified timeout.
+     */
+    public enqueue<T>(promise: DeferredPromise<void, T>, timeout: number): TimedPromise<T>;
+
+    /**
+     * Enqueues a callback that returns a {@link MaybePromise} value of type `T` into the queue.
+     *
+     * The executor will be executed in sequence after previously enqueued promises.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const queue = new PromiseQueue();
+     *
+     * queue.enqueue(() => console.log("Hello, world!")); // "Hello, world!"
+     * ```
+     *
+     * ---
+     *
+     * @template T The type of value the promise will eventually resolve to.
+     *
+     * @param executor A callback that returns a `MaybePromise<T>` value to enqueue.
+     *
+     * @returns A {@link Promise} that resolves to the value of the enqueued executor.
+     */
+    public enqueue<T>(executor: Callback<[], MaybePromise<T>>): Promise<T>;
+
+    /**
+     * Enqueues a callback that returns a {@link MaybePromise}
+     * value of type `T` into the queue with an optional timeout.
+     *
+     * The executor will be executed in sequence after previously enqueued promises.  
+     * If the executor takes longer than the specified timeout, it will be rejected with a {@link TimeoutException}.
+     *
+     * ---
+     *
+     * @example
+     * ```ts
+     * const queue = new PromiseQueue();
+     *
+     * queue.enqueue(() => console.log("Hello, world!"), 5000); // "Hello, world!"
+     * ```
+     *
+     * ---
+     *
+     * @template T The type of value the promise will eventually resolve to.
+     *
+     * @param executor A callback that returns a `MaybePromise<T>` value to enqueue.
+     * @param timeout The maximum time in milliseconds that the operation can take before timing out.
+     *
+     * @returns
+     * A {@link TimedPromise} that resolves to the value of the enqueued executor or rejects
+     * with a `TimeoutException` if the operation takes longer than the specified timeout.
+     */
+    public enqueue<T>(executor: Callback<[], MaybePromise<T>>, timeout?: number): TimedPromise<T>;
+    public enqueue<T>(executor: DeferredPromise<void, T> | Callback<[], MaybePromise<T>>, timeout?: number)
+        : Promise<T> | TimedPromise<T>
+    {
+        this._count += 1;
+
+        if (executor instanceof DeferredPromise)
+        {
+            const _executor = executor as DeferredPromise<void, T>;
+
+            executor = () =>
+            {
+                _executor.resolve();
+
+                return _executor;
+            };
+        }
+
+        const _executor = (resolve: PromiseResolver<T>, reject: PromiseRejecter) =>
+        {
+            this._promise = this._promise
+                .then(executor)
+                .then((value) => { this._count -= 1; resolve(value); })
+                .catch((value) => { this._count -= 1; reject(value); });
+        };
+
+        if (timeout) { return new TimedPromise<T>(_executor, timeout); }
+
+        return new Promise<T>(_executor);
+    }
+
+    public override readonly [Symbol.toStringTag]: string = "PromiseQueue";
+}

package/src/models/timers/clock.ts

@@ -24,9 +24,9 @@ interface ClockEventsMap
  * ```ts
  * const clock = new Clock();
  *
- * clock.onStart(() => { console.log("The clock has started."); });
- * clock.onTick((elapsedTime) => { console.log(`The clock has ticked at ${elapsedTime}ms.`); });
- * clock.onStop(() => { console.log("The clock has stopped."); });
+ * clock.onStart(() => console.log("The clock has started."));
+ * clock.onTick((elapsedTime) => console.log(`The clock has ticked at ${elapsedTime}ms.`));
+ * clock.onStop(() => console.log("The clock has stopped."));
  *
  * clock.start();
  * ```

package/src/models/timers/countdown.ts

@@ -30,10 +30,10 @@ interface CountdownEventsMap
  * ```ts
  * const countdown = new Countdown(10_000);
  *
- * countdown.onStart(() => { console.log("The countdown has started."); });
- * countdown.onTick((remainingTime) => { console.log(`The countdown has ${remainingTime}ms remaining.`); });
- * countdown.onStop((reason) => { console.log(`The countdown has stopped because of ${reason}.`); });
- * countdown.onExpire(() => { console.log("The countdown has expired."); });
+ * countdown.onStart(() => console.log("The countdown has started."));
+ * countdown.onTick((remainingTime) => console.log(`The countdown has ${remainingTime}ms remaining.`));
+ * countdown.onStop((reason) => console.log(`The countdown has stopped because of ${reason}.`));
+ * countdown.onExpire(() => console.log("The countdown has expired."));
  *
  * countdown.start();
  * ```

package/src/models/timers/game-loop.ts

@@ -32,8 +32,8 @@ interface GameLoopEventsMap
  *     console.log(`The game loop has been running for ${elapsedTime}ms.`);
  * });
  *
- * loop.onStart(() => { console.log("The game loop has started."); });
- * loop.onStop(() => { console.log("The game loop has stopped."); });
+ * loop.onStart(() => console.log("The game loop has started."));
+ * loop.onStop(() => console.log("The game loop has stopped."));
  *
  * loop.start();
  * ```
@@ -226,7 +226,7 @@ export default class GameLoop
      *
      * @example
      * ```ts
-     * loop.onStart(() => { console.log("The game loop has started."); });
+     * loop.onStart(() => console.log("The game loop has started."));
      * ```
      *
      * ---
@@ -247,7 +247,7 @@ export default class GameLoop
      *
      * @example
      * ```ts
-     * loop.onStop(() => { console.log("The game loop has stopped."); });
+     * loop.onStop(() => console.log("The game loop has stopped."));
      * ```
      *
      * ---

package/src/models/types.ts

@@ -38,4 +38,12 @@ export type {
 
 } from "./promises/types.js";
 
-export type { Callback, CallbackMap, Publishable, Subscribable } from "./callbacks/types.js";
+export type {
+    Callback,
+    CallbackMap,
+    InternalsEventsMap,
+    WildcardEventsMap,
+    Publishable,
+    Subscribable
+
+} from "./callbacks/types.js";