@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

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.

import { AsyncExecutionStack } from '@push.rocks/lik';

const stack = new AsyncExecutionStack();

// Exclusive execution (sequential, blocks other tasks)
await stack.getExclusiveExecutionSlot(async () => {
  // critical section work
}, 5000); // optional timeout in ms

// 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.

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

A high-performance key-value map optimized for rapid lookups and modifications.

import { FastMap } from '@push.rocks/lik';

const map = new FastMap<string>();

map.addToMap('key1', 'value1');
map.addToMap('key2', 'value2');

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');

InterestMap

Manages subscriptions/interests in events or entities. Multiple parties can express interest in the same thing; the interest is deduplicated and fulfilled once.

import { InterestMap } from '@push.rocks/lik';

const interestMap = new InterestMap<string, number>(
  (str) => str, // comparison function to deduplicate interests
  { markLostAfterDefault: 30000 } // optional: auto-mark lost after 30s
);

// 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>

LimitedArray

An array that automatically enforces a maximum size, discarding oldest items when the limit is exceeded.

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.

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.

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.

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.

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.

import { Tree } from '@push.rocks/lik';

class TreeNode {
  constructor(public value: string) {}
}

const tree = new Tree<TreeNode>();
const root = new TreeNode('root');
tree.initialize(root);

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);

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 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.

Trademarks

This 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.

readme.md

@push.rocks/lik

Install

Usage