push.rocks/lik
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(tooling): update build tooling, developer dependencies, npmextra configuration, and expand README documentation

Browse Source
This commit is contained in:
Jürgen Kunz
2026-03-01 12:29:44 +00:00
parent 47d339bb2b
commit 03a33195bc
6 changed files with 3559 additions and 1284 deletions
Download Patch File Download Diff File Expand all files Collapse all files

398
readme.md
View File

@@ -1,193 +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` provides controlled execution of asynchronous tasks in two modes:
Controls 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:
- **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 stack = new AsyncExecutionStack();
```
Exclusive tasks execute sequentially and block subsequent tasks (with an optional timeout):
// Exclusive execution (sequential, blocks other tasks)
await stack.getExclusiveExecutionSlot(async () => {
// critical section work
}, 5000); // optional timeout in ms
```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
// Non-exclusive execution (parallel)
const p1 = stack.getNonExclusiveExecutionSlot(async () => {
// work 1
}, 2000);
// concurrent work 1
});
const p2 = stack.getNonExclusiveExecutionSlot(async () => {
// work 2
}, 2000);
// 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
```
Control concurrency and inspect status:
### 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
// Set maximum concurrent non-exclusive tasks (minimum 1)
stack.setNonExclusiveMaxConcurrency(3);
import { BackpressuredArray } from '@push.rocks/lik';
console.log(stack.getNonExclusiveMaxConcurrency()); // 3
console.log(stack.getActiveNonExclusiveCount()); // currently running tasks
console.log(stack.getPendingNonExclusiveCount()); // tasks waiting for slots
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';
@@ -196,28 +268,36 @@ 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.
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.
**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.
@@ -227,7 +307,7 @@ This project is owned and maintained by Task Venture Capital GmbH. The names and
### Company Information
Task Venture Capital GmbH
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.