@byloth/core 2.1.4 → 2.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byloth/core",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "description": "An unopinionated collection of useful functions and classes that I use widely in all my projects. 🔧",
   "keywords": [
     "Core",
@@ -51,9 +51,9 @@
   "devDependencies": {
     "@byloth/eslint-config-typescript": "^3.1.0",
     "@eslint/compat": "^1.3.0",
-    "@types/node": "^22.15.31",
+    "@types/node": "^22.15.32",
     "@vitest/coverage-v8": "^3.2.3",
-    "eslint": "^9.28.0",
+    "eslint": "^9.29.0",
     "husky": "^9.1.7",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",

package/src/core/types.ts

@@ -74,7 +74,7 @@ export type Timeout = ReturnType<typeof setTimeout>;
  *     public greet() { console.log("Hello, world!"); }
  * }
  *
- * type MyObjectProperties = ValueOf<MyObject>;  // number | (() => void)
+ * type MyObjectProperties = ValueOf<MyObject>; // number | (() => void)
  * ```
  *
  * ---

package/src/index.ts

@@ -1,4 +1,4 @@
-export const VERSION = "2.1.4";
+export const VERSION = "2.1.5";
 
 export type { Constructor, Interval, Timeout, ValueOf } from "./core/types.js";
 
@@ -24,6 +24,7 @@ export {
     NotImplementedException,
     NetworkException,
     PermissionException,
+    PromiseQueue,
     Publisher,
     RangeException,
     ReducedIterator,

package/src/models/callbacks/publisher.ts

@@ -125,6 +125,10 @@ export default class Publisher<T extends CallbackMap<T> = CallbackMap, W extends
      * Default is `T`.
      *
      * @template X An utility type that extends the `U` map with a wildcard event.
+     *
+     * @return
+     * A new instance of the {@link Publisher} class that can be
+     * used to publish and subscribe events within a specific context.
      */
     public createScope<U extends T = T, X extends WithWildcard<U> = WithWildcard<U>>(): Publisher<U, X>
     {

package/src/models/index.ts

@@ -29,5 +29,5 @@ export {
 
 export { SmartIterator, SmartAsyncIterator } from "./iterators/index.js";
 export { JSONStorage } from "./json/index.js";
-export { DeferredPromise, SmartPromise, TimedPromise } from "./promises/index.js";
+export { DeferredPromise, PromiseQueue, SmartPromise, TimedPromise } from "./promises/index.js";
 export { Clock, Countdown, GameLoop } from "./timers/index.js";

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";
+}