v6.3.1

changelog.md

@@ -0,0 +1,104 @@
+# Changelog
+
+## 2026-03-01 - 6.3.1 - fix(classes)
+cleanup resources, add cancellable timeouts, and fix bugs in several core utility classes
+
+- Replace one-shot delayFor usage with plugins.smartdelay.Timeout in AsyncExecutionStack so timeouts are cancellable and properly cleaned up on success or error
+- Add destroy() to BackpressuredArray to complete subjects and unblock waiters; waitForSpace/waitForItems now respect destruction to avoid hangs
+- Make Interest instances cancel mark-lost timers and guard against double-destroy; destruction now clears fulfillment store and resolves default fulfillment without mutual recursion
+- Add InterestMap.destroy() to clean up all interests and complete observable
+- ObjectMap: removeMappedUnique now returns removed object and emits a remove event; wipe now emits remove events for cleared entries and destroy() completes eventSubject
+- StringMap.destroy() clears stored strings and pending triggers
+- TimedAggregtor: add stop(flushRemaining) and isStopped guards to stop timer chain and optionally flush remaining items
+- LoopTracker: add reset() and destroy() helpers to clear and destroy internal maps
+- Fix compareTreePosition to call symbolTree.compareTreePosition instead of recursively calling itself
+
+## 2026-03-01 - 6.3.0 - feat(tooling)
+update build tooling, developer dependencies, npmextra configuration, and expand README documentation
+
+- Bump devDependencies for @git.zone toolchain and related packages (@git.zone/tsbuild, tsbundle, tsrun, tstest, @push.rocks/tapbundle, @types/node)
+- Bump runtime deps: @push.rocks/smartrx and @push.rocks/smarttime
+- Adjust npm build script: remove trailing 'npm' argument from tsbundle invocation
+- Rework npmextra.json: rename/unify keys to @git.zone/* scoped entries, add release registries and accessLevel, add tsbundle bundle configuration, and reorganize CI/tool settings
+- Significant README rewrite: expanded descriptions, clearer usage examples and API snippets, formatting and example updates
+
+## 2026-03-01 - 6.2.3 - fix(interestmap)
+remove interest from InterestMap immediately after fulfillment
+
+- Call destroy() in fullfillInterest to remove the interest entry from the InterestMap right after resolving interestDeferred.
+- Prevents stale entries and ensures immediate cleanup of fulfilled interests
+
+## 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
+
+- Implemented a new method `checkHasItems` in the BackpressuredArray class to determine if the array contains any items.
+
+## 2024-05-29 to 2024-04-18 - 6.0.15
+Minor updates were made to documentation and descriptions.
+
+- Update project description
+
+## 2024-04-18 to 2024-02-25 - 6.0.14
+Several updates were made to configurations and json files.
+
+- Updated core components in the codebase
+- Modified tsconfig settings
+- Revised npmextra.json with githost configurations
+
+## 2024-02-25 to 2024-02-23 - 6.0.13
+No relevant changes.
+
+## 2024-02-23 to 2023-11-13 - 6.0.12 to 6.0.8
+Multiple core updates were performed to ensure stability and performance.
+
+- Fixed various issues in core components
+
+## 2023-11-13 to 2023-08-14 - 6.0.7 to 6.0.3
+Minor internal core updates.
+
+## 2023-08-14 to 2023-07-12 - 6.0.2
+Implemented a switch to a new organizational scheme.
+
+## 2023-01-18 to 2022-05-27 - 6.0.0
+Updated core functionalities; introduced breaking changes for compatibility with ECMAScript modules.
+
+- Core updates
+- Switching from CommonJS to ECMAScript modules
+
+## 2022-05-27 to 2022-05-27 - 5.0.6 to 5.0.0
+Minor updates and a significant change in `objectmap` behavior to support async operations.
+
+- Included async behaviors in objectmap as a breaking change
+
+## 2020-05-04 to 2020-02-17 - 4.0.0
+Refactored ObjectMap; introduced new features.
+
+- Refactored ObjectMap with concat functionality as a breaking change
+- Added .clean() to FastMap
+
+## 2020-02-17 to 2020-02-06 - 3.0.19 to 3.0.15
+Enhancements and new functionality in ObjectMap.
+
+- Added object mapping enhancements
+- Introduced object map with unique keys

npmextra.json

@@ -1,9 +1,5 @@
 {
-  "npmci": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public"
-  },
-  "gitzone": {
+  "@git.zone/cli": {
     "projectType": "npm",
     "module": {
       "githost": "code.foss.global",
@@ -25,9 +21,29 @@
         "Event handling",
         "Data aggregation"
       ]
+    },
+    "release": {
+      "registries": [
+        "https://verdaccio.lossless.digital",
+        "https://registry.npmjs.org"
+      ],
+      "accessLevel": "public"
     }
   },
-  "tsdoc": {
+  "@git.zone/tsdoc": {
     "legal": "\n## License and Legal Information\n\nThis repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. \n\n**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.\n\n### Trademarks\n\nThis project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.\n\n### Company Information\n\nTask Venture Capital GmbH  \nRegistered at District court Bremen HRB 35230 HB, Germany\n\nFor any legal inquiries or if you require further information, please contact us via email at hello@task.vc.\n\nBy using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.\n"
+  },
+  "@git.zone/tsbundle": {
+    "bundles": [
+      {
+        "from": "./ts/index.ts",
+        "to": "./dist_bundle/bundle.js",
+        "outputMode": "bundle",
+        "bundler": "esbuild"
+      }
+    ]
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": []
   }
 }

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/lik",
-  "version": "6.0.15",
+  "version": "6.3.1",
   "private": false,
   "description": "Provides a collection of lightweight helpers and utilities for Node.js projects.",
   "main": "dist_ts/index.js",
@@ -8,33 +8,33 @@
   "type": "module",
   "scripts": {
     "test": "(tstest test/)",
-    "build": "(tsbuild --web --allowimplicitany && tsbundle npm)",
+    "build": "(tsbuild --web --allowimplicitany && tsbundle)",
     "buildDocs": "tsdoc"
   },
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@gitlab.com/pushrocks/lik.git"
+    "url": "https://code.foss.global/push.rocks/lik.git"
   },
   "author": "Lossless GmbH",
   "license": "MIT",
   "bugs": {
     "url": "https://gitlab.com/pushrocks/lik/issues"
   },
-  "homepage": "https://gitlab.com/pushrocks/lik#README",
+  "homepage": "https://code.foss.global/push.rocks/lik",
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.72",
-    "@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"
+    "@git.zone/tsbuild": "^4.1.2",
+    "@git.zone/tsbundle": "^2.9.0",
+    "@git.zone/tsrun": "^2.0.1",
+    "@git.zone/tstest": "^3.1.8",
+    "@push.rocks/tapbundle": "^6.0.3",
+    "@types/node": "^25.3.3"
   },
   "dependencies": {
     "@push.rocks/smartdelay": "^3.0.5",
     "@push.rocks/smartmatch": "^2.0.0",
     "@push.rocks/smartpromise": "^4.0.3",
-    "@push.rocks/smartrx": "^3.0.7",
-    "@push.rocks/smarttime": "^4.0.6",
+    "@push.rocks/smartrx": "^3.0.10",
+    "@push.rocks/smarttime": "^4.2.3",
     "@types/minimatch": "^5.1.2",
     "@types/symbol-tree": "^3.2.5",
     "symbol-tree": "^3.2.4"
@@ -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

@@ -1,162 +1,265 @@
 # @push.rocks/lik
-light little helpers for node
+
+A collection of lightweight utility classes for TypeScript/Node.js projects, providing efficient data structures and async helpers.
 
 ## Install
 
-To install `@push.rocks/lik`, you can use npm (Node Package Manager). Simply run the following command in your terminal:
-
 ```bash
-npm install @push.rocks/lik --save
+npm install @push.rocks/lik
 ```
 
-This will download `@push.rocks/lik` and add it to your project's `package.json` dependencies.
-
 ## Usage
 
-`@push.rocks/lik` is a versatile package offering a variety of helper classes designed to simplify common tasks in Node.js development. From managing asynchronous operations to handling collections efficiently, this library provides lightweight solutions to enhance your coding workflow. Below, we explore several key features of `@push.rocks/lik`, presenting TypeScript examples to demonstrate their practical application in real-world scenarios.
+`@push.rocks/lik` provides a set of focused helper classes for common programming tasks: managing collections, controlling async execution, tracking interests, and more. All classes are fully typed and work in both Node.js and browser environments.
 
 ### AsyncExecutionStack
 
-`AsyncExecutionStack` allows for managing asynchronous task execution with exclusive and non-exclusive slots, ensuring effective handling of resource-intensive operations.
+Controls execution of asynchronous tasks in two modes:
+
+- **Exclusive**: tasks run one at a time, blocking all others until complete.
+- **Non-exclusive**: tasks run in parallel with optional concurrency limits.
 
 ```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 execution (sequential, blocks other tasks)
+await stack.getExclusiveExecutionSlot(async () => {
+  // critical section work
+}, 5000); // optional timeout in ms
 
-// Non-exclusive slots can run in parallel
-myAsyncStack.getNonExclusiveExecutionSlot(async () => {
-  // another asynchronous operation
-}, 1500);
+// Non-exclusive execution (parallel)
+const p1 = stack.getNonExclusiveExecutionSlot(async () => {
+  // concurrent work 1
+});
+const p2 = stack.getNonExclusiveExecutionSlot(async () => {
+  // concurrent work 2
+});
+await Promise.all([p1, p2]);
+
+// Control concurrency
+stack.setNonExclusiveMaxConcurrency(3);
+console.log(stack.getNonExclusiveMaxConcurrency()); // 3
+console.log(stack.getActiveNonExclusiveCount());    // currently running
+console.log(stack.getPendingNonExclusiveCount());   // waiting for slots
+```
+
+### BackpressuredArray
+
+An array with backpressure support using RxJS subjects. Useful for producer/consumer patterns where you need to throttle the producer when the consumer can't keep up.
+
+```typescript
+import { BackpressuredArray } from '@push.rocks/lik';
+
+const buffer = new BackpressuredArray<string>(16); // high water mark of 16
+
+// Producer: push items, returns false when full
+const hasSpace = buffer.push('item1');
+if (!hasSpace) {
+  await buffer.waitForSpace(); // wait until consumer frees space
+}
+
+// Consumer: shift items out
+await buffer.waitForItems(); // wait until items are available
+const item = buffer.shift();
+
+// Check state
+buffer.checkSpaceAvailable(); // true if below high water mark
+buffer.checkHasItems();       // true if items exist
 ```
 
 ### FastMap
 
-`FastMap` offers a high-performance, key-value map optimized for rapid access and modifications, ideal for scenarios requiring frequent read/write operations.
+A high-performance key-value map optimized for rapid lookups and modifications.
 
 ```typescript
 import { FastMap } from '@push.rocks/lik';
 
-const myFastMap = new FastMap<string>();
+const map = new FastMap<string>();
 
-// Add items
-myFastMap.addToMap('key1', 'value1');
-myFastMap.addToMap('key2', 'value2');
+map.addToMap('key1', 'value1');
+map.addToMap('key2', 'value2');
 
-// Retrieve item
-const value = myFastMap.getByKey('key1'); // 'value1'
+const value = map.getByKey('key1'); // 'value1'
+map.isUniqueKey('key1');            // false (already exists)
+map.removeFromMap('key1');
+
+// Merge maps
+const otherMap = new FastMap<string>();
+otherMap.addToMap('key3', 'value3');
+const merged = map.concat(otherMap);
+
+// Or merge in place
+map.addAllFromOther(otherMap);
+
+// Async find
+const found = await map.find(async (item) => item === 'value2');
 ```
 
-### LimitedArray
+### InterestMap
 
-`LimitedArray` enforces a maximum size on an array, automatically managing its length to prevent it from exceeding a defined limit.
-
-```typescript
-import { LimitedArray } from '@push.rocks/lik';
-
-const myLimitedArray = new LimitedArray<number>(5); // limit size to 5
-
-myLimitedArray.addMany([1, 2, 3, 4, 5, 6]);
-console.log(myLimitedArray.array); // [2, 3, 4, 5, 6]
-```
-
-### LoopTracker
-
-`LoopTracker` helps detect and prevent infinite loops by tracking object references during iterations.
-
-```typescript
-import { LoopTracker } from '@push.rocks/lik';
-
-const myLoopTracker = new LoopTracker<object>();
-const obj1 = {};
-
-if (myLoopTracker.checkAndTrack(obj1)) {
-  // proceed with operation
-} else {
-  // potential loop detected
-}
-```
-
-### ObjectMap
-
-`ObjectMap` facilitates object management, providing functionalities for adding, finding, and removing objects with ease.
-
-```typescript
-import { ObjectMap } from '@push.rocks/lik';
-
-interface MyObject {
-  id: number;
-  name: string;
-}
-
-const myObjectMap = new ObjectMap<MyObject>();
-const obj: MyObject = { id: 1, name: 'Test Object' };
-
-// Add object
-myObjectMap.add(obj);
-
-// Find object
-const found = myObjectMap.findSync(item => item.id === 1);
-```
-
-### StringMap
-
-`StringMap` simplifies string collection management, allowing you to add, remove, and query strings effectively.
-
-```typescript
-import { Stringmap } from '@push.rocks/lik';
-
-const myStringMap = new Stringmap();
-
-// Add strings
-myStringMap.addString('hello');
-myStringMap.addStringArray(['world', 'example']);
-
-// Check string presence
-const exists = myStringMap.checkString('hello'); // true
-```
-
-### TimedAggregator
-
-`TimedAggregator` batches operations over a specified time interval, useful for aggregating logs, metrics, or any data points over time.
-
-```typescript
-import { TimedAggregtor } from '@push.rocks/lik';
-
-const myAggregator = new TimedAggregtor<string>({
-  aggregationIntervalInMillis: 5000, // 5 seconds
-  functionForAggregation: (items) => {
-    console.log('Aggregated items:', items);
-  }
-});
-
-// Add items
-myAggregator.add('item1');
-myAggregator.add('item2');
-
-// After 5 seconds, the functionForAggregation will log the aggregated items
-```
-
-### InterestMap and Tree
-
-`InterestMap` provides a structure for managing subscriptions or interests in certain events or entities, optimizing notification mechanisms.
+Manages subscriptions/interests in events or entities. Multiple parties can express interest in the same thing; the interest is deduplicated and fulfilled once.
 
 ```typescript
 import { InterestMap } from '@push.rocks/lik';
 
-const myInterestMap = new InterestMap<string, number>((str) => str);
+const interestMap = new InterestMap<string, number>(
+  (str) => str, // comparison function to deduplicate interests
+  { markLostAfterDefault: 30000 } // optional: auto-mark lost after 30s
+);
 
-myInterestMap.addInterest('event1').then((interest) => {
-  interest.fullfillInterest(42);
+// Express interest
+const interest = await interestMap.addInterest('event1');
+
+// Wait for fulfillment
+interest.interestFullfilled.then((result) => {
+  console.log('Got result:', result);
 });
+
+// Fulfill from elsewhere
+const found = interestMap.findInterest('event1');
+found.fullfillInterest(42);
+
+// Check and manage interests
+interestMap.checkInterest('event1'); // true/false
+interestMap.informLostInterest('event1'); // starts destruction timer
+
+// Observable stream of new interests
+interestMap.interestObservable; // ObservableIntake<Interest>
 ```
 
-`Tree` offers a way to handle hierarchical data structures, allowing for the composition and traversal of tree-like data sets.
+### LimitedArray
+
+An array that automatically enforces a maximum size, discarding oldest items when the limit is exceeded.
+
+```typescript
+import { LimitedArray } from '@push.rocks/lik';
+
+const arr = new LimitedArray<number>(5);
+
+arr.addMany([1, 2, 3, 4, 5, 6]);
+console.log(arr.array.length); // 5 (oldest items dropped)
+
+arr.addOne(7);
+arr.setLimit(3); // dynamically adjust limit
+
+// Compute average (for numeric arrays)
+const numArr = new LimitedArray<number>(10);
+numArr.addMany([10, 20, 30]);
+console.log(numArr.getAverage()); // 20
+```
+
+### LoopTracker
+
+Detects and prevents infinite loops by tracking object references during iterations.
+
+```typescript
+import { LoopTracker } from '@push.rocks/lik';
+
+const tracker = new LoopTracker<object>();
+const obj1 = {};
+
+tracker.checkAndTrack(obj1); // true (first time, tracked)
+tracker.checkAndTrack(obj1); // false (already seen - loop detected!)
+```
+
+### ObjectMap
+
+A managed collection of objects with add/remove/find operations and event notifications via RxJS.
+
+```typescript
+import { ObjectMap } from '@push.rocks/lik';
+
+interface IUser {
+  id: number;
+  name: string;
+}
+
+const users = new ObjectMap<IUser>();
+
+// Add objects
+const key = users.add({ id: 1, name: 'Alice' });
+users.addArray([{ id: 2, name: 'Bob' }, { id: 3, name: 'Carol' }]);
+
+// Find objects
+const alice = users.findSync((u) => u.id === 1);
+const bob = await users.find(async (u) => u.id === 2);
+
+// Find and remove in one step
+const removed = await users.findOneAndRemove(async (u) => u.id === 3);
+const removedSync = users.findOneAndRemoveSync((u) => u.id === 2);
+
+// Direct add/get by unique key
+users.addMappedUnique('admin', { id: 99, name: 'Admin' });
+const admin = users.getMappedUnique('admin');
+
+// Get one and remove (FIFO-style)
+const first = users.getOneAndRemove();
+
+// Iterate, check, and manage
+await users.forEach((u) => console.log(u.name));
+users.checkForObject(alice);  // true/false
+users.isEmpty();               // true/false
+users.getArray();              // cloned array of all objects
+users.wipe();                  // remove all
+
+// Listen for changes
+users.eventSubject.subscribe((event) => {
+  console.log(event.operation, event.payload); // 'add' | 'remove'
+});
+
+// Merge object maps
+const merged = users.concat(otherObjectMap);
+users.addAllFromOther(otherObjectMap);
+```
+
+### Stringmap
+
+Manages a collection of strings with add/remove/query operations and minimatch pattern matching.
+
+```typescript
+import { Stringmap } from '@push.rocks/lik';
+
+const strings = new Stringmap();
+
+strings.addString('hello');
+strings.addStringArray(['world', 'example']);
+
+strings.checkString('hello');       // true
+strings.checkMinimatch('hel*');     // true (glob matching)
+strings.checkIsEmpty();             // false
+
+strings.removeString('hello');
+strings.getStringArray();           // ['world', 'example']
+
+// Register trigger that fires when condition is met
+await strings.registerUntilTrue((arr) => arr.length === 0);
+strings.wipe(); // triggers the above
+```
+
+### TimedAggregator
+
+Batches items over a time interval, then processes them in bulk. Useful for aggregating logs, metrics, or events.
+
+```typescript
+import { TimedAggregtor } from '@push.rocks/lik';
+
+const aggregator = new TimedAggregtor<string>({
+  aggregationIntervalInMillis: 5000,
+  functionForAggregation: (items) => {
+    console.log('Batch:', items);
+  },
+});
+
+aggregator.add('event1');
+aggregator.add('event2');
+// After 5 seconds: Batch: ['event1', 'event2']
+```
+
+### Tree
+
+A typed wrapper around `symbol-tree` for managing hierarchical data structures with parent/child/sibling relationships.
 
 ```typescript
 import { Tree } from '@push.rocks/lik';
@@ -165,25 +268,33 @@ class TreeNode {
   constructor(public value: string) {}
 }
 
-const myTree = new Tree<TreeNode>();
-const rootNode = new TreeNode('root');
-myTree.initialize(rootNode);
+const tree = new Tree<TreeNode>();
+const root = new TreeNode('root');
+tree.initialize(root);
 
-// Add child nodes
-const childNode = new TreeNode('child');
-myTree.appendChild(rootNode, childNode);
+const child1 = new TreeNode('child1');
+const child2 = new TreeNode('child2');
+tree.appendChild(root, child1);
+tree.appendChild(root, child2);
+
+// Navigate
+tree.hasChildren(root);        // true
+tree.firstChild(root);         // child1
+tree.lastChild(root);          // child2
+tree.nextSibling(child1);     // child2
+tree.parent(child1);           // root
+
+// Query
+tree.childrenCount(root);     // 2
+tree.index(child2);           // 1
+tree.childrenToArray(root, {}); // [child1, child2]
+tree.treeToArray(root, {});     // full tree as array
+
+// Mutate
+tree.insertBefore(child2, new TreeNode('between'));
+tree.remove(child2);
 ```
 
-### Utilizing @push.rocks/lik in Your Project
-
-With `@push.rocks/lik`, you gain access to a comprehensive set of lightweight utilities that can significantly simplify and expedite the development process in Node.js environments. By leveraging the library's classes and functions, you can implement efficient data structures, manage asynchronous operations gracefully, and streamline complex logic with ease.
-
-By integrating `@push.rocks/lik` into your project, you'll benefit from improved code clarity, reduced boilerplate, and enhanced performance, allowing you to focus on developing the core functionalities of your application. Whether you're managing various collections, executing asynchronous tasks in controlled manners, or dealing with hierarchical data, `@push.rocks/lik` provides the tools you need to achieve your objectives with minimal overhead.
-
-Remember, continuous exploration of `@push.rocks/lik`'s capabilities and experimenting with its various components in different scenarios will help you unlock its full potential. As your familiarity with the library grows, you'll discover even more ways to optimize your codebase and streamline your development workflow.
-
-
-
 ## License and Legal Information
 
 This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.

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

@@ -1,8 +1,8 @@
 /**
- * autocreated commitinfo by @pushrocks/commitinfo
+ * autocreated commitinfo by @push.rocks/commitinfo
  */
 export const commitinfo = {
   name: '@push.rocks/lik',
-  version: '6.0.15',
+  version: '6.3.1',
   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) {
@@ -69,13 +97,20 @@ export class AsyncExecutionStack {
   private async executeExclusiveSlot(slot: IExecutionSlot<any>) {
     try {
       if (slot.timeout) {
+        const timeoutInstance = new plugins.smartdelay.Timeout(slot.timeout);
+        try {
           const result = await Promise.race([
             slot.funcToExecute(),
-          plugins.smartdelay.delayFor(slot.timeout).then(() => {
+            timeoutInstance.promise.then(() => {
               throw new Error('Timeout reached');
             }),
           ]);
+          timeoutInstance.cancel();
           slot.executionDeferred.resolve(result);
+        } catch (error) {
+          timeoutInstance.cancel();
+          throw error;
+        }
       } else {
         const result = await slot.funcToExecute();
         slot.executionDeferred.resolve(result);
@@ -87,24 +122,56 @@ 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 timeoutInstance = new plugins.smartdelay.Timeout(slot.timeout);
+          try {
             const result = await Promise.race([
               slot.funcToExecute(),
-            plugins.smartdelay.delayFor(slot.timeout).then(() => {
-              throw new Error('Timeout reached');
-            }),
+              timeoutInstance.promise.then(() => { throw new Error('Timeout reached'); }),
             ]);
+            timeoutInstance.cancel();
             slot.executionDeferred.resolve(result);
+          } catch (error) {
+            timeoutInstance.cancel();
+            throw error;
+          }
         } else {
           const result = await slot.funcToExecute();
           slot.executionDeferred.resolve(result);
         }
       } 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();
+    }
+  }
 }

ts/classes.backpressuredarray.ts

@@ -5,6 +5,7 @@ export class BackpressuredArray<T> {
   private highWaterMark: number;
   public hasSpace = new plugins.smartrx.rxjs.Subject<'hasSpace'>();
   private itemsAvailable = new plugins.smartrx.rxjs.Subject<'itemsAvailable'>();
+  private isDestroyed = false;
 
   constructor(highWaterMark: number = 16) {
     this.data = [];
@@ -34,14 +35,23 @@ export class BackpressuredArray<T> {
     return this.data.length < this.highWaterMark;
   }
 
+  public checkHasItems(): boolean {
+    return this.data.length > 0;
+  }
+
   waitForSpace(): Promise<void> {
     return new Promise<void>((resolve) => {
-      if (this.checkSpaceAvailable()) {
+      if (this.checkSpaceAvailable() || this.isDestroyed) {
         resolve();
       } else {
-        const subscription = this.hasSpace.subscribe(() => {
+        const subscription = this.hasSpace.subscribe({
+          next: () => {
             subscription.unsubscribe();
             resolve();
+          },
+          complete: () => {
+            resolve();
+          },
         });
       }
     });
@@ -49,14 +59,28 @@ export class BackpressuredArray<T> {
 
   waitForItems(): Promise<void> {
     return new Promise<void>((resolve) => {
-      if (this.data.length > 0) {
+      if (this.data.length > 0 || this.isDestroyed) {
         resolve();
       } else {
-        const subscription = this.itemsAvailable.subscribe(() => {
+        const subscription = this.itemsAvailable.subscribe({
+          next: () => {
             subscription.unsubscribe();
             resolve();
+          },
+          complete: () => {
+            resolve();
+          },
         });
       }
     });
   }
+
+  /**
+   * destroys the BackpressuredArray, completing all subjects
+   */
+  public destroy() {
+    this.isDestroyed = true;
+    this.hasSpace.complete();
+    this.itemsAvailable.complete();
+  }
 }

ts/classes.interestmap.interest.ts

@@ -15,12 +15,18 @@ export class Interest<DTInterestId, DTInterestFullfillment> {
   public comparisonFunc: IInterestComparisonFunc<DTInterestId>;
   public destructionTimer = new plugins.smarttime.Timer(10000);
   public isFullfilled = false;
+  private isDestroyed = false;
 
   /**
    * a generic store to store objects in that are needed for fullfillment;
    */
   public fullfillmentStore: any[] = [];
 
+  /**
+   * a cancellable timeout for the markLostAfterDefault feature
+   */
+  private markLostTimeout: InstanceType<typeof plugins.smartdelay.Timeout> | null = null;
+
   /**
    * quick access to a string that makes the interest comparable for checking for similar interests
    */
@@ -39,11 +45,9 @@ export class Interest<DTInterestId, DTInterestFullfillment> {
     this.isFullfilled = true;
     this.fullfillmentStore = [];
     this.interestDeferred.resolve(objectArg);
+    this.destroy();
   }
 
-  /**
-   *
-   */
   constructor(
     interestMapArg: InterestMap<DTInterestId, DTInterestFullfillment>,
     interestArg: DTInterestId,
@@ -56,10 +60,17 @@ export class Interest<DTInterestId, DTInterestFullfillment> {
     this.options = optionsArg;
 
     this.destructionTimer.completed.then(() => {
+      if (!this.isDestroyed) {
         this.destroy();
+      }
     });
     if (this.options?.markLostAfterDefault) {
-      plugins.smartdelay.delayFor(this.options.markLostAfterDefault).then(this.markLost);
+      this.markLostTimeout = new plugins.smartdelay.Timeout(this.options.markLostAfterDefault);
+      this.markLostTimeout.promise.then(() => {
+        if (!this.isDestroyed) {
+          this.markLost();
+        }
+      });
     }
   }
 
@@ -71,9 +82,28 @@ export class Interest<DTInterestId, DTInterestFullfillment> {
    * self destructs the interest
    */
   public destroy() {
+    if (this.isDestroyed) {
+      return;
+    }
+    this.isDestroyed = true;
+
+    // Cancel timers to release references
+    this.destructionTimer.reset();
+    if (this.markLostTimeout) {
+      this.markLostTimeout.cancel();
+      this.markLostTimeout = null;
+    }
+
+    // Clear the fulfillment store
+    this.fullfillmentStore = [];
+
+    // Remove from the InterestMap
     this.interestMapRef.removeInterest(this);
-    if (!this.isFullfilled && this.options.defaultFullfillment) {
-      this.fullfillInterest(this.options.defaultFullfillment);
+
+    // Fulfill with default if not yet fulfilled (inlined to avoid mutual recursion)
+    if (!this.isFullfilled && this.options?.defaultFullfillment) {
+      this.isFullfilled = true;
+      this.interestDeferred.resolve(this.options.defaultFullfillment);
     }
   }
 

ts/classes.interestmap.ts

@@ -70,6 +70,8 @@ export class InterestMap<DTInterestId, DTInterestFullfillment> {
     if (!returnInterest) {
       returnInterest = newInterest;
       this.interestObjectMap.add(returnInterest);
+    } else {
+      newInterest.destroy(); // clean up abandoned Interest's timers
     }
     this.interestObservable.push(returnInterest);
     return returnInterest;
@@ -131,4 +133,16 @@ export class InterestMap<DTInterestId, DTInterestFullfillment> {
     });
     return interest; // if an interest is found, the interest is returned, otherwise interest is null
   }
+
+  /**
+   * destroys the InterestMap and cleans up all resources
+   */
+  public destroy() {
+    const interests = this.interestObjectMap.getArray();
+    for (const interest of interests) {
+      interest.destroy();
+    }
+    this.interestObjectMap.wipe();
+    this.interestObservable.signalComplete();
+  }
 }

ts/classes.looptracker.ts

@@ -20,4 +20,18 @@ export class LoopTracker<T> {
       return false;
     }
   }
+
+  /**
+   * resets the loop tracker, clearing all tracked objects
+   */
+  public reset() {
+    this.referenceObjectMap.wipe();
+  }
+
+  /**
+   * destroys the loop tracker and its underlying ObjectMap
+   */
+  public destroy() {
+    this.referenceObjectMap.destroy();
+  }
 }

ts/classes.objectmap.ts

@@ -62,8 +62,15 @@ export class ObjectMap<T> {
    * remove key
    * @param functionArg
    */
-  public removeMappedUnique(uniqueKey: string) {
-    const object = this.getMappedUnique(uniqueKey);
+  public removeMappedUnique(uniqueKey: string): T {
+    const object = this.fastMap.removeFromMap(uniqueKey);
+    if (object !== undefined) {
+      this.eventSubject.next({
+        operation: 'remove',
+        payload: object,
+      });
+    }
+    return object;
   }
 
   /**
@@ -220,8 +227,13 @@ export class ObjectMap<T> {
    * wipe Objectmap
    */
   public wipe() {
-    for (const keyArg of this.fastMap.getKeys()) {
-      this.fastMap.removeFromMap(keyArg);
+    const keys = this.fastMap.getKeys();
+    for (const keyArg of keys) {
+      const removedObject = this.fastMap.removeFromMap(keyArg);
+      this.eventSubject.next({
+        operation: 'remove',
+        payload: removedObject,
+      });
     }
   }
 
@@ -243,4 +255,12 @@ export class ObjectMap<T> {
   public addAllFromOther(objectMapArg: ObjectMap<T>) {
     this.fastMap.addAllFromOther(objectMapArg.fastMap);
   }
+
+  /**
+   * destroys the ObjectMap, completing the eventSubject and clearing all entries
+   */
+  public destroy() {
+    this.wipe();
+    this.eventSubject.complete();
+  }
 }

ts/classes.stringmap.ts

@@ -116,4 +116,12 @@ export class Stringmap {
     });
     this._triggerUntilTrueFunctionArray = filteredArray;
   }
+
+  /**
+   * destroys the Stringmap, clearing all strings and pending triggers
+   */
+  public destroy() {
+    this._stringArray = [];
+    this._triggerUntilTrueFunctionArray = [];
+  }
 }

ts/classes.timedaggregator.ts

@@ -8,6 +8,7 @@ export interface ITimedAggregatorOptions<T> {
 export class TimedAggregtor<T> {
   public options: ITimedAggregatorOptions<T>;
   private storageArray: T[] = [];
+  private isStopped = false;
 
   constructor(optionsArg: ITimedAggregatorOptions<T>) {
     this.options = optionsArg;
@@ -15,9 +16,16 @@ export class TimedAggregtor<T> {
 
   private aggregationTimer: plugins.smarttime.Timer;
   private checkAggregationStatus() {
+    if (this.isStopped) {
+      return;
+    }
     const addAggregationTimer = () => {
       this.aggregationTimer = new plugins.smarttime.Timer(this.options.aggregationIntervalInMillis);
       this.aggregationTimer.completed.then(() => {
+        if (this.isStopped) {
+          this.aggregationTimer = null;
+          return;
+        }
         const aggregateForProcessing = this.storageArray;
         if (aggregateForProcessing.length === 0) {
           this.aggregationTimer = null;
@@ -35,7 +43,29 @@ export class TimedAggregtor<T> {
   }
 
   public add(aggregationArg: T) {
+    if (this.isStopped) {
+      return;
+    }
     this.storageArray.push(aggregationArg);
     this.checkAggregationStatus();
   }
+
+  /**
+   * stops the aggregation timer chain
+   * @param flushRemaining if true, calls functionForAggregation with any remaining items
+   */
+  public stop(flushRemaining: boolean = false) {
+    this.isStopped = true;
+    if (this.aggregationTimer) {
+      this.aggregationTimer.reset();
+      this.aggregationTimer = null;
+    }
+    if (flushRemaining && this.storageArray.length > 0) {
+      const remaining = this.storageArray;
+      this.storageArray = [];
+      this.options.functionForAggregation(remaining);
+    } else {
+      this.storageArray = [];
+    }
+  }
 }

ts/classes.tree.ts

@@ -95,7 +95,7 @@ export class Tree<T> {
   }
 
   compareTreePosition(leftArg: T, rightArg: T): number {
-    return this.compareTreePosition(leftArg, rightArg);
+    return this.symbolTree.compareTreePosition(leftArg, rightArg);
   }
 
   remove(removeObjectArg: T): T {