diff --git a/changelog.md b/changelog.md index f28c2d1..192331a 100644 --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,12 @@ # 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 diff --git a/package.json b/package.json index d419400..df0f907 100644 --- a/package.json +++ b/package.json @@ -26,7 +26,7 @@ "@git.zone/tsbundle": "^2.0.15", "@git.zone/tsrun": "^1.2.44", "@git.zone/tstest": "^1.0.90", - "@push.rocks/tapbundle": "^5.0.8", + "@push.rocks/tapbundle": "^5.5.6", "@types/node": "^22.13.9" }, "dependencies": { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 1dc1ad9..8932fe2 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -46,7 +46,7 @@ importers: specifier: ^1.0.90 version: 1.0.96(@aws-sdk/credential-providers@3.758.0)(socks@2.8.4)(typescript@5.7.3) '@push.rocks/tapbundle': - specifier: ^5.0.8 + specifier: ^5.5.6 version: 5.5.6(@aws-sdk/credential-providers@3.758.0)(socks@2.8.4) '@types/node': specifier: ^22.13.9 diff --git a/readme.md b/readme.md index f4c56e9..7a66185 100644 --- a/readme.md +++ b/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 diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts index 9516470..7ce243c 100644 --- a/ts/00_commitinfo_data.ts +++ b/ts/00_commitinfo_data.ts @@ -3,6 +3,6 @@ */ export const commitinfo = { name: '@push.rocks/lik', - version: '6.2.1', + version: '6.2.2', description: 'Provides a collection of lightweight helpers and utilities for Node.js projects.' }