6.2.2

changelog.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 2025-04-25 - 6.2.2 - fix(docs)
+Update @push.rocks/tapbundle dependency and refine AsyncExecutionStack documentation examples
+
+- Bump @push.rocks/tapbundle from ^5.0.8 to ^5.5.6 in package.json
+- Improve README documentation for AsyncExecutionStack with clearer examples for exclusive and non-exclusive task execution
+- Demonstrate usage of concurrency controls in AsyncExecutionStack
+
+## 2025-04-25 - 6.2.1 - fix(AsyncExecutionStack tests)
+Refactor AsyncExecutionStack tests: update non-exclusive concurrency assertions and clean up test logic
+
+- Replace 'toBe' with 'toEqual' for active and pending counts to ensure consistency
+- Simplify default non-exclusive concurrency test by asserting Infinity is non-finite using toBeFalse
+- Adjust test comments and scheduling for clarity in concurrency behavior
+
+## 2025-04-25 - 6.2.0 - feat(AsyncExecutionStack)
+Improve non-exclusive task management with concurrency limit controls and enhanced monitoring in AsyncExecutionStack.
+
+- Added methods to set and get non-exclusive concurrency limits and statistics (setNonExclusiveMaxConcurrency, getActiveNonExclusiveCount, getPendingNonExclusiveCount, and getNonExclusiveMaxConcurrency).
+- Integrated proper waiting and release mechanisms for non-exclusive slots.
+- Extended test coverage to validate concurrency limits and ensure correct behavior.
+
 ## 2024-10-13 - 6.1.0 - feat(BackpressuredArray)
 Add method to check if items are present in BackpressuredArray
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/lik",
-  "version": "6.1.0",
+  "version": "6.2.2",
   "private": false,
   "description": "Provides a collection of lightweight helpers and utilities for Node.js projects.",
   "main": "dist_ts/index.js",
@@ -26,8 +26,8 @@
     "@git.zone/tsbundle": "^2.0.15",
     "@git.zone/tsrun": "^1.2.44",
     "@git.zone/tstest": "^1.0.90",
-    "@push.rocks/tapbundle": "^5.0.8",
-    "@types/node": "^20.12.7"
+    "@push.rocks/tapbundle": "^5.5.6",
+    "@types/node": "^22.13.9"
   },
   "dependencies": {
     "@push.rocks/smartdelay": "^3.0.5",
@@ -66,5 +66,13 @@
     "Asynchronous programming",
     "Event handling",
     "Data aggregation"
+  ],
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "esbuild",
+      "mongodb-memory-server",
+      "puppeteer"
     ]
+  },
+  "packageManager": "pnpm@10.7.0+sha512.6b865ad4b62a1d9842b61d674a393903b871d9244954f652b8842c2b553c72176b278f64c463e52d40fff8aba385c235c8c9ecf5cc7de4fd78b8bb6d49633ab6"
 }

readme.md

@@ -17,22 +17,53 @@ This will download `@push.rocks/lik` and add it to your project's `package.json`
 
 ### AsyncExecutionStack
 
-`AsyncExecutionStack` allows for managing asynchronous task execution with exclusive and non-exclusive slots, ensuring effective handling of resource-intensive operations.
+`AsyncExecutionStack` provides controlled execution of asynchronous tasks in two modes:
+
+- **Exclusive tasks**: run one at a time in insertion order, blocking all other tasks until complete.
+- **Non-exclusive tasks**: run in parallel, up to an optional concurrency limit.
+
+Create a stack:
 
 ```typescript
 import { AsyncExecutionStack } from '@push.rocks/lik';
 
-const myAsyncStack = new AsyncExecutionStack();
+const stack = new AsyncExecutionStack();
+```
 
-// Exclusive execution ensures this task doesn't run in parallel with others
-await myAsyncStack.getExclusiveExecutionSlot(async () => {
-  // some asynchronous operation
-}, 2500);
+Exclusive tasks execute sequentially and block subsequent tasks (with an optional timeout):
 
-// Non-exclusive slots can run in parallel
-myAsyncStack.getNonExclusiveExecutionSlot(async () => {
-  // another asynchronous operation
-}, 1500);
+```typescript
+await stack.getExclusiveExecutionSlot(
+  async () => {
+    // exclusive work
+  },
+  5000 // optional timeout in milliseconds
+);
+```
+
+Non-exclusive tasks run in parallel up to the concurrency limit (default: unlimited). Each call returns a promise you can await:
+
+```typescript
+const p1 = stack.getNonExclusiveExecutionSlot(async () => {
+  // work 1
+}, 2000);
+
+const p2 = stack.getNonExclusiveExecutionSlot(async () => {
+  // work 2
+}, 2000);
+
+await Promise.all([p1, p2]);
+```
+
+Control concurrency and inspect status:
+
+```typescript
+// Set maximum concurrent non-exclusive tasks (minimum 1)
+stack.setNonExclusiveMaxConcurrency(3);
+
+console.log(stack.getNonExclusiveMaxConcurrency()); // 3
+console.log(stack.getActiveNonExclusiveCount());    // currently running tasks
+console.log(stack.getPendingNonExclusiveCount());   // tasks waiting for slots
 ```
 
 ### FastMap

test/test.asyncexecutionstack.both.ts

@@ -26,4 +26,66 @@ tap.test('should run in parallel', async (toolsArg) => {
   }, 0);
 });
 
+// Test default non-exclusive has no concurrency limit property (Infinity)
+tap.test('default non-exclusive has no concurrency limit', () => {
+  const stack = new lik.AsyncExecutionStack();
+  // default maxConcurrency is Infinity (not finite)
+  expect(Number.isFinite(stack.getNonExclusiveMaxConcurrency())).toBeFalse();
+});
+// Test respecting a non-exclusive concurrency limit
+tap.test('non-exclusive respects maxConcurrency', async (tools) => {
+  const stack = new lik.AsyncExecutionStack();
+  stack.setNonExclusiveMaxConcurrency(2);
+  const activeCounts: number[] = [];
+  const tasks: Promise<void>[] = [];
+  for (let i = 0; i < 5; i++) {
+    tasks.push(
+      stack.getNonExclusiveExecutionSlot(async () => {
+        activeCounts.push(stack.getActiveNonExclusiveCount());
+        await tools.delayFor(50);
+      })
+    );
+  }
+  await Promise.all(tasks);
+  // never more than 2 at once
+  const maxActive = Math.max(...activeCounts);
+  expect(maxActive).toBeLessThanOrEqual(2);
+});
+
+// Test concurrency stats (active vs pending) for non-exclusive tasks
+tap.test('non-exclusive concurrency stats reflect active and pending', async (tools) => {
+  const stack = new lik.AsyncExecutionStack();
+  stack.setNonExclusiveMaxConcurrency(2);
+  // initially, no tasks
+  expect(stack.getActiveNonExclusiveCount()).toEqual(0);
+  expect(stack.getPendingNonExclusiveCount()).toEqual(0);
+
+  // enqueue four tasks
+  const p1 = stack.getNonExclusiveExecutionSlot(async () => {
+    await tools.delayFor(30);
+  });
+  const p2 = stack.getNonExclusiveExecutionSlot(async () => {
+    await tools.delayFor(30);
+  });
+  const p3 = stack.getNonExclusiveExecutionSlot(async () => {
+    await tools.delayFor(30);
+  });
+  const p4 = stack.getNonExclusiveExecutionSlot(async () => {
+    await tools.delayFor(30);
+  });
+
+  // wait for first task to finish and scheduling of next batch
+  await p1;
+  await tools.delayFor(0);
+  // second batch: two active, one pending (4 tasks, limit=2)
+  expect(stack.getActiveNonExclusiveCount()).toEqual(2);
+  expect(stack.getPendingNonExclusiveCount()).toEqual(1);
+
+  // wait for remaining tasks to complete
+  await Promise.all([p2, p3, p4]);
+  // after completion, counts reset
+  expect(stack.getActiveNonExclusiveCount()).toEqual(0);
+  expect(stack.getPendingNonExclusiveCount()).toEqual(0);
+});
+
 export default tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/lik',
-  version: '6.1.0',
+  version: '6.2.2',
   description: 'Provides a collection of lightweight helpers and utilities for Node.js projects.'
 }

ts/classes.asyncexecutionstack.ts

@@ -10,6 +10,12 @@ interface IExecutionSlot<T> {
 export class AsyncExecutionStack {
   private executionSlots: IExecutionSlot<any>[] = [];
   private isProcessing = false;
+  /** Maximum concurrent non-exclusive tasks (Infinity = unlimited) */
+  private nonExclusiveMaxConcurrency: number = Infinity;
+  /** Currently running non-exclusive task count */
+  private nonExclusiveCurrentCount: number = 0;
+  /** Queue of resolvers waiting for a non-exclusive slot */
+  private nonExclusivePendingQueue: Array<() => void> = [];
 
   public async getExclusiveExecutionSlot<T = any>(
     funcArg: () => Promise<T>,
@@ -42,6 +48,28 @@ export class AsyncExecutionStack {
     this.processExecutionSlots();
     return executionDeferred.promise;
   }
+  /**
+   * Set the maximum number of concurrent non-exclusive tasks.
+   * @param concurrency minimum 1 (Infinity means unlimited)
+   */
+  public setNonExclusiveMaxConcurrency(concurrency: number): void {
+    if (!Number.isFinite(concurrency) || concurrency < 1) {
+      throw new Error('nonExclusiveMaxConcurrency must be a finite number >= 1');
+    }
+    this.nonExclusiveMaxConcurrency = concurrency;
+  }
+  /** Get the configured max concurrency for non-exclusive tasks */
+  public getNonExclusiveMaxConcurrency(): number {
+    return this.nonExclusiveMaxConcurrency;
+  }
+  /** Number of non-exclusive tasks currently running */
+  public getActiveNonExclusiveCount(): number {
+    return this.nonExclusiveCurrentCount;
+  }
+  /** Number of non-exclusive tasks waiting for a free slot */
+  public getPendingNonExclusiveCount(): number {
+    return this.nonExclusivePendingQueue.length;
+  }
 
   private async processExecutionSlots() {
     if (this.isProcessing) {
@@ -87,13 +115,14 @@ export class AsyncExecutionStack {
 
   private async executeNonExclusiveSlots(slots: IExecutionSlot<any>[]) {
     const promises = slots.map(async (slot) => {
+      // wait for an available non-exclusive slot
+      await this.waitForNonExclusiveSlot();
       try {
+        // execute with optional timeout
         if (slot.timeout) {
           const result = await Promise.race([
             slot.funcToExecute(),
-            plugins.smartdelay.delayFor(slot.timeout).then(() => {
-              throw new Error('Timeout reached');
-            }),
+            plugins.smartdelay.delayFor(slot.timeout).then(() => { throw new Error('Timeout reached'); }),
           ]);
           slot.executionDeferred.resolve(result);
         } else {
@@ -102,9 +131,33 @@ export class AsyncExecutionStack {
         }
       } catch (error) {
         slot.executionDeferred.reject(error);
+      } finally {
+        this.releaseNonExclusiveSlot();
       }
     });
-
     await Promise.all(promises);
   }
+  /**
+   * Wait until a non-exclusive slot is available (respects max concurrency).
+   */
+  private waitForNonExclusiveSlot(): Promise<void> {
+    if (this.nonExclusiveCurrentCount < this.nonExclusiveMaxConcurrency) {
+      this.nonExclusiveCurrentCount++;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.nonExclusivePendingQueue.push(() => {
+        this.nonExclusiveCurrentCount++;
+        resolve();
+      });
+    });
+  }
+  /** Release a non-exclusive slot and wake the next waiter, if any. */
+  private releaseNonExclusiveSlot(): void {
+    this.nonExclusiveCurrentCount--;
+    const next = this.nonExclusivePendingQueue.shift();
+    if (next) {
+      next();
+    }
+  }
 }