@augment-vir/common 30.2.0 → 30.4.0

package/dist/augments/promise/promise-queue.d.ts

@@ -0,0 +1,86 @@
+import { DeferredPromise, type MaybePromise } from '@augment-vir/core';
+import type { RequireExactlyOne } from 'type-fest';
+import { ListenTarget } from 'typed-event-target';
+/**
+ * An individual item in a {@link PromiseQueue} instance.
+ *
+ * @category Promise : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PromiseQueueItem<T = void> = {
+    /** The original queue item that was added. */
+    original: () => MaybePromise<T>;
+    /**
+     * A {@link DeferredPromise} instance with a promise that is resolved once this queue item has
+     * met its turn and has finished executing.
+     */
+    wrapper: DeferredPromise<T>;
+};
+/**
+ * Data contained within an instance of {@link PromiseQueueUpdateEvent}.
+ *
+ * @category Promise : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type PromiseQueueUpdate<T = unknown> = {
+    queueSize: number;
+} & RequireExactlyOne<{
+    finishedItem: PromiseQueueItem<T>;
+    addedItem: PromiseQueueItem<T>;
+}>;
+declare const PromiseQueueUpdateEvent_base: (new (eventInitDict: {
+    bubbles?: boolean;
+    cancelable?: boolean;
+    composed?: boolean;
+    detail: PromiseQueueUpdate<unknown>;
+}) => import("typed-event-target").TypedCustomEvent<PromiseQueueUpdate<unknown>, "promise-queue-update">) & Pick<{
+    new (type: string, eventInitDict?: EventInit): Event;
+    prototype: Event;
+    readonly NONE: 0;
+    readonly CAPTURING_PHASE: 1;
+    readonly AT_TARGET: 2;
+    readonly BUBBLING_PHASE: 3;
+}, "prototype" | "NONE" | "CAPTURING_PHASE" | "AT_TARGET" | "BUBBLING_PHASE"> & Pick<import("typed-event-target").TypedCustomEvent<PromiseQueueUpdate<unknown>, "promise-queue-update">, "type">;
+/**
+ * The event emitted from a {@link PromiseQueue} instance whenever the queue is updated (an item is
+ * resolved or an item is added).
+ *
+ * @category Promise : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare class PromiseQueueUpdateEvent extends PromiseQueueUpdateEvent_base {
+}
+/**
+ * A queue that manages its items with promises.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare class PromiseQueue extends ListenTarget<PromiseQueueUpdateEvent> {
+    protected queue: PromiseQueueItem<any>[];
+    protected currentlyAwaiting: undefined | PromiseQueueItem<any>;
+    /** The current size of the queue. */
+    get size(): number;
+    /**
+     * Add an item to the queue.
+     *
+     * @returns A promise that resolves at the same time as the added item.
+     */
+    add<T = void>(item: PromiseQueueItem<T>['original']): Promise<T>;
+    /** Handles a queue item finishing, whether it be a rejection or a resolution. */
+    protected handleItemSettle({ rejection, resolution, }: RequireExactlyOne<{
+        rejection: unknown;
+        resolution: unknown;
+    }>): PromiseQueueItem<any>;
+    /**
+     * Tries to trigger the next queue item, if there is one.
+     *
+     * @returns Whether a new queue item was triggered or not. `true` if it was, otherwise `false`.
+     */
+    protected triggerNextQueueItem(): boolean;
+}
+export {};

package/dist/augments/promise/promise-queue.js

@@ -0,0 +1,91 @@
+import { check } from '@augment-vir/assert';
+import { DeferredPromise } from '@augment-vir/core';
+import { defineTypedCustomEvent, ListenTarget } from 'typed-event-target';
+/**
+ * The event emitted from a {@link PromiseQueue} instance whenever the queue is updated (an item is
+ * resolved or an item is added).
+ *
+ * @category Promise : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export class PromiseQueueUpdateEvent extends defineTypedCustomEvent()('promise-queue-update') {
+}
+/**
+ * A queue that manages its items with promises.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export class PromiseQueue extends ListenTarget {
+    queue = [];
+    currentlyAwaiting = undefined;
+    /** The current size of the queue. */
+    get size() {
+        return this.queue.length;
+    }
+    /**
+     * Add an item to the queue.
+     *
+     * @returns A promise that resolves at the same time as the added item.
+     */
+    add(item) {
+        const newItem = {
+            original: item,
+            wrapper: new DeferredPromise(),
+        };
+        this.queue.push(newItem);
+        this.dispatch(new PromiseQueueUpdateEvent({
+            detail: {
+                queueSize: this.size,
+                addedItem: newItem,
+            },
+        }));
+        this.triggerNextQueueItem();
+        return newItem.wrapper.promise;
+    }
+    /** Handles a queue item finishing, whether it be a rejection or a resolution. */
+    handleItemSettle({ rejection, resolution, }) {
+        const item = this.currentlyAwaiting;
+        if (!item) {
+            throw new Error(`Cannot handle queue item settle without a currently awaited queue item.`);
+        }
+        this.queue.splice(0, 1);
+        this.dispatch(new PromiseQueueUpdateEvent({
+            detail: {
+                queueSize: this.size,
+                finishedItem: item,
+            },
+        }));
+        if (rejection) {
+            item.wrapper.reject(rejection);
+        }
+        else {
+            item.wrapper.resolve(resolution);
+        }
+        this.currentlyAwaiting = undefined;
+        this.triggerNextQueueItem();
+        return item;
+    }
+    /**
+     * Tries to trigger the next queue item, if there is one.
+     *
+     * @returns Whether a new queue item was triggered or not. `true` if it was, otherwise `false`.
+     */
+    triggerNextQueueItem() {
+        if (this.currentlyAwaiting || !check.isLengthAtLeast(this.queue, 1)) {
+            return false;
+        }
+        const item = this.queue[0];
+        this.currentlyAwaiting = item;
+        item.original()
+            .then((result) => {
+            this.handleItemSettle({ resolution: result });
+        })
+            .catch((error) => {
+            this.handleItemSettle({ rejection: error });
+        });
+        return true;
+    }
+}

package/dist/index.d.ts

@@ -84,3 +84,8 @@ export * from './augments/type/type-recursion.js';
 export * from './augments/type/union.js';
 export * from './augments/type/void-type.js';
 export * from './augments/type/writable.js';
+/**
+ * This must be placed last to account for this depending on `typed-listen-target` which depends on
+ * part of `@augment-vir/common`.
+ */
+export * from './augments/promise/promise-queue.js';

package/dist/index.js

@@ -84,3 +84,8 @@ export * from './augments/type/type-recursion.js';
 export * from './augments/type/union.js';
 export * from './augments/type/void-type.js';
 export * from './augments/type/writable.js';
+/**
+ * This must be placed last to account for this depending on `typed-listen-target` which depends on
+ * part of `@augment-vir/common`.
+ */
+export * from './augments/promise/promise-queue.js';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@augment-vir/common",
-    "version": "30.2.0",
+    "version": "30.4.0",
     "description": "A collection of augments, helpers types, functions, and classes for any JavaScript environment.",
     "keywords": [
         "augment",
@@ -39,22 +39,23 @@
         "test:web": "virmator --no-deps test web"
     },
     "dependencies": {
-        "@augment-vir/assert": "^30.2.0",
-        "@augment-vir/core": "^30.2.0",
+        "@augment-vir/assert": "^30.4.0",
+        "@augment-vir/core": "^30.4.0",
         "@date-vir/duration": "^6.0.1",
         "ansi-styles": "^6.2.1",
         "json5": "^2.2.3",
-        "type-fest": "^4.26.1"
+        "type-fest": "^4.26.1",
+        "typed-event-target": "^4.0.2"
     },
     "devDependencies": {
-        "@web/dev-server-esbuild": "^1.0.2",
+        "@web/dev-server-esbuild": "^1.0.3",
         "@web/test-runner": "^0.19.0",
         "@web/test-runner-commands": "^0.9.0",
         "@web/test-runner-playwright": "^0.11.0",
         "@web/test-runner-visual-regression": "^0.10.0",
-        "concurrently": "^9.0.1",
+        "concurrently": "^9.1.0",
         "execute-in-browser": "^1.0.3",
-        "istanbul-smart-text-reporter": "^1.1.4"
+        "istanbul-smart-text-reporter": "^1.1.5"
     },
     "engines": {
         "node": ">=22"