v5.0.0

changelog.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 2026-02-15 - 5.0.0 - BREAKING CHANGE(taskbuffer)
+Introduce constraint-based concurrency with TaskConstraintGroup and TaskManager integration; remove legacy TaskRunner and several Task APIs (breaking); add typed Task.data and update exports and tests.
+
+- Add TaskConstraintGroup class with per-key maxConcurrent, cooldownMs, and helper methods (canRun, acquireSlot, releaseSlot, getCooldownRemaining, getRunningCount, reset).
+- Task generic signature extended to Task<T, TSteps, TData> and a new typed data property (data) with default {}.
+- TaskManager now supports addConstraintGroup/removeConstraintGroup, triggerTaskConstrained, queues blocked tasks, drains queue with cooldown timers, and routes triggerTask/triggerTaskByName through the constraint system.
+- Removed TaskRunner, plus Task APIs: blockingTasks, execDelay, finished promise and associated behavior have been removed (breaking changes).
+- Exports and interfaces updated: TaskConstraintGroup and ITaskConstraintGroupOptions added; TaskRunner removed from public API.
+- Updated README and added comprehensive tests for constraint behavior; adjusted other tests to remove TaskRunner usage and reflect new APIs.
+
+## 2026-02-15 - 4.2.1 - fix(deps)
+bump @push.rocks/smartlog and @types/node; update dependency list version and license link in docs
+
+- package.json: update @push.rocks/smartlog from ^3.1.10 to ^3.1.11
+- package.json: update @types/node from ^25.1.0 to ^25.2.3
+- readme.hints.md: update 'Dependencies (as of v4.1.1)' to 'Dependencies (as of v4.2.0)' and reflect bumped dependency versions
+- readme.md: change license link text to '[LICENSE](./license.md)'
+
+## 2026-01-29 - 4.2.0 - feat(ts_web)
+support TC39 'accessor' decorators for web components; bump dependencies and devDependencies; rename browser tests to .chromium.ts; move LICENSE to license.md and update readme
+
+- Convert web component class fields to use the TC39 'accessor' keyword in ts_web/taskbuffer-dashboard.ts to be compatible with @design.estate/dees-element v2.1.6
+- Bump @design.estate/dees-element to ^2.1.6 and update devDependencies (@git.zone/tsbuild, @git.zone/tsbundle, @git.zone/tsrun, @git.zone/tstest, @types/node) to newer versions
+- Replace test/test.10.webcomponent.browser.ts with test/test.10.webcomponent.chromium.ts and update testing guidance in readme.hints.md to prefer .chromium.ts
+- Move LICENSE file content to license.md and update readme.md to reference the new license file
+- Small test cleanups: remove obsolete tslint:disable comments
+
+## 2026-01-26 - 4.1.1 - fix(ts_web)
+fix web dashboard typings and update generated commit info
+
+- Updated generated commit info file ts_web/00_commitinfo_data.ts to version 4.1.0
+- Large changes applied to web/TS build files (net +529 additions, -399 deletions) — likely fixes and typing/refactor improvements in ts_web/dashboard
+- package.json remains at 4.1.0; recommend a patch bump to 4.1.1 for these fixes
+
+## 2026-01-26 - 4.1.0 - feat(task)
+add task labels and push-based task events
+
+- Introduce Task labels: Task accepts labels in constructor and exposes setLabel/getLabel/removeLabel/hasLabel; labels are included (shallow copy) in getMetadata().
+- Add push-based events: Task.eventSubject (rxjs Subject<ITaskEvent>) emits 'started','step','completed','failed' with timestamp; 'step' includes stepName and 'failed' includes error string.
+- Task now emits events during lifecycle: emits 'started' at run start, 'step' on notifyStep, and 'completed' or 'failed' when finished or errored. getMetadata() now includes labels.
+- TaskManager aggregates task events into taskSubject, subscribes on addTask and unsubscribes on removeTask/stop; includes helper methods getTasksByLabel and getTasksMetadataByLabel.
+- Public API updated: exported ITaskEvent and TTaskEventType in ts/index.ts and interfaces updated (labels in metadata, new event types).
+- Tests and docs: added test/test.12.labels-and-events.ts and updated readme.hints.md to document labels and push-based events.
+
 ## 2026-01-25 - 4.0.0 - BREAKING CHANGE(taskbuffer)
 Change default Task error handling: trigger() now rejects when taskFunction throws; add catchErrors option (default false) to preserve previous swallow behavior; track errors (lastError, errorCount) and expose them in metadata; improve error propagation and logging across runners, chains, parallels and debounced tasks; add tests and documentation for new behavior.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@push.rocks/taskbuffer",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "private": false,
   "description": "A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.",
   "main": "dist_ts/index.js",
@@ -27,28 +27,28 @@
     "debounced tasks",
     "distributed coordination"
   ],
-  "author": "Lossless GmbH",
+  "author": "Task Venture Capital GmbH <hello@task.vc>",
   "license": "MIT",
   "bugs": {
     "url": "https://code.foss.global/push.rocks/taskbuffer/issues"
   },
   "homepage": "https://code.foss.global/push.rocks/taskbuffer#readme",
   "dependencies": {
-    "@design.estate/dees-element": "^2.1.3",
+    "@design.estate/dees-element": "^2.1.6",
     "@push.rocks/lik": "^6.2.2",
     "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartlog": "^3.1.10",
+    "@push.rocks/smartlog": "^3.1.11",
     "@push.rocks/smartpromise": "^4.2.3",
     "@push.rocks/smartrx": "^3.0.10",
     "@push.rocks/smarttime": "^4.1.1",
     "@push.rocks/smartunique": "^3.0.9"
   },
   "devDependencies": {
-    "@git.zone/tsbuild": "^3.1.2",
-    "@git.zone/tsbundle": "^2.6.3",
-    "@git.zone/tsrun": "^2.0.0",
-    "@git.zone/tstest": "^3.1.3",
-    "@types/node": "^24.10.1"
+    "@git.zone/tsbuild": "^4.1.2",
+    "@git.zone/tsbundle": "^2.8.3",
+    "@git.zone/tsrun": "^2.0.1",
+    "@git.zone/tstest": "^3.1.8",
+    "@types/node": "^25.2.3"
   },
   "files": [
     "ts/**/*",

readme.hints.md

@@ -1,28 +1,91 @@
 # Taskbuffer Hints
 
+## Task Constraint System (v5.0.0+) — Breaking Changes
+- **`TaskRunner` removed** — replaced by `TaskManager` + `TaskConstraintGroup`
+- **`blockingTasks` removed** from `Task` — use `TaskConstraintGroup` with `maxConcurrent: 1`
+- **`execDelay` removed** from `Task` — use `TaskConstraintGroup` with `cooldownMs`
+- **`finished` promise removed** from `Task` — no longer needed
+- **`Task` generic signature**: `Task<T, TSteps, TData>` (3rd param added for typed data)
+
+### Task.data
+- `Task` constructor accepts optional `data?: TData` (defaults to `{}`)
+- Typed data bag accessible as `task.data`
+
+### TaskConstraintGroup
+- `new TaskConstraintGroup<TData>({ name, constraintKeyForTask, maxConcurrent?, cooldownMs? })`
+- `constraintKeyForTask(task)` returns a string key (constraint applies) or `null` (skip)
+- `maxConcurrent` (default: `Infinity`) — max concurrent tasks per key
+- `cooldownMs` (default: `0`) — minimum ms gap between completions per key
+- Methods: `canRun(key)`, `acquireSlot(key)`, `releaseSlot(key)`, `getCooldownRemaining(key)`, `getRunningCount(key)`, `reset()`
+
+### TaskManager Constraint Integration
+- `manager.addConstraintGroup(group)` / `manager.removeConstraintGroup(name)`
+- `triggerTaskByName()`, `triggerTask()`, `addExecuteRemoveTask()`, cron callbacks all route through `triggerTaskConstrained()`
+- `triggerTaskConstrained(task, input?)` — evaluates constraints, queues if blocked, drains after completion
+- Cooldown-blocked entries auto-drain via timer
+
+### Exported from index.ts
+- `TaskConstraintGroup` class
+- `ITaskConstraintGroupOptions` type
+
 ## Error Handling (v3.6.0+)
 - `Task` now has `catchErrors` constructor option (default: `false`)
 - Default behavior: `trigger()` rejects when taskFunction throws (breaking change from pre-3.6)
 - Set `catchErrors: true` to swallow errors (old behavior) - returns `undefined` on error
 - Error state tracked via `lastError?: Error`, `errorCount: number`, `clearError()`
 - `getMetadata()` status uses all four values: `'idle'` | `'running'` | `'completed'` | `'failed'`
-- All peripheral classes (Taskchain, Taskparallel, TaskRunner, BufferRunner, TaskDebounced, TaskManager) have proper error propagation/handling
+- All peripheral classes (Taskchain, Taskparallel, BufferRunner, TaskDebounced, TaskManager) have proper error propagation/handling
 - `console.log` calls replaced with `logger.log()` throughout
 
-## Breaking API Rename (TaskRunner)
-- `maxParrallelJobs` → `maxParallelJobs`
-- `qeuedTasks` → `queuedTasks`
-- JSDoc typos fixed: "qeue" → "queue", "wether" → "whether", "loose" → "lose"
-- The `setMaxParallelJobs()` parameter also renamed from `maxParrallelJobsArg` to `maxParallelJobsArg`
-
 ## Error Context Improvements
 - **TaskChain**: Errors now wrap the original with context: chain name, failing task name, and task index. Original error preserved via `.cause`
 - **BufferRunner**: When `catchErrors: false`, buffered task errors now reject the trigger promise (via `CycleCounter.informOfCycleError`) instead of silently resolving with `undefined`
 - **TaskChain stubs completed**: `removeTask(task)` returns `boolean`, `shiftTask()` returns `Task | undefined`
 
+## Task Labels (v4.1.0+)
+- `Task` constructor accepts optional `labels?: Record<string, string>`
+- Helper methods: `setLabel(key, value)`, `getLabel(key)`, `removeLabel(key)`, `hasLabel(key, value?)`
+- `getMetadata()` includes `labels` (shallow copy)
+- `TaskManager.getTasksByLabel(key, value)` returns matching `Task[]`
+- `TaskManager.getTasksMetadataByLabel(key, value)` returns matching `ITaskMetadata[]`
+
+## Push-Based Events (v4.1.0+)
+- `Task.eventSubject`: rxjs `Subject<ITaskEvent>` emitting `'started'`, `'step'`, `'completed'`, `'failed'` events
+- `TaskManager.taskSubject`: aggregated `Subject<ITaskEvent>` from all added tasks
+- `TaskManager.removeTask(task)` unsubscribes and removes from map
+- `TaskManager.stop()` cleans up all event subscriptions
+- Exported types: `ITaskEvent`, `TTaskEventType`
+
 ## Project Structure
 - Source in `ts/`, web components in `ts_web/`
-- Tests in `test/` - naming: `*.node.ts`, `*.browser.ts`, `*.both.ts`
+- Tests in `test/` - naming: `*.node.ts`, `*.chromium.ts` (preferred), `*.both.ts`
+  - Note: `*.browser.ts` is deprecated, use `*.chromium.ts` for browser tests
 - Logger: `ts/taskbuffer.logging.ts` exports `logger` (ConsoleLog from smartlog)
 - Build: `pnpm build` (tsbuild tsfolders)
 - Test: `pnpm test` or `tstest test/test.XX.name.ts --verbose`
+
+## Web Components (ts_web/)
+- Uses `@design.estate/dees-element` with TC39 decorators
+- Decorators require the `accessor` keyword:
+  ```typescript
+  @property({ type: String })
+  accessor myProp = 'default';
+
+  @state()
+  accessor count = 0;
+  ```
+
+## Dependencies (as of v4.2.0)
+- `@design.estate/dees-element` ^2.1.6 - TC39 decorators with `accessor` keyword
+- `@push.rocks/lik` ^6.2.2 - Data structures
+- `@push.rocks/smartdelay` ^3.0.5 - Delay utilities
+- `@push.rocks/smartlog` ^3.1.11 - Logging
+- `@push.rocks/smartpromise` ^4.2.3 - Promise utilities
+- `@push.rocks/smartrx` ^3.0.10 - RxJS wrapper
+- `@push.rocks/smarttime` ^4.1.1 - Time/cron utilities
+- `@push.rocks/smartunique` ^3.0.9 - Unique ID generation
+- `@git.zone/tsbuild` ^4.1.2 - Build tool
+- `@git.zone/tsbundle` ^2.8.3 - Bundler (for browser tests)
+- `@git.zone/tsrun` ^2.0.1 - TypeScript runner
+- `@git.zone/tstest` ^3.1.8 - Test runner (supports `.chromium.ts` files)
+- `@types/node` ^25.2.3 - Node.js type definitions

test/test.11.errorhandling.ts

@@ -137,38 +137,7 @@ tap.test('should reject Taskparallel when a child task throws', async () => {
   expect(didReject).toBeTrue();
 });
 
-// Test 7: TaskRunner continues processing after a task error
-tap.test('should continue TaskRunner queue after a task error', async () => {
-  const runner = new taskbuffer.TaskRunner();
-  const executionOrder: string[] = [];
-
-  const badTask = new taskbuffer.Task({
-    name: 'runner-bad-task',
-    taskFunction: async () => {
-      executionOrder.push('bad');
-      throw new Error('runner task failure');
-    },
-  });
-  const goodTask = new taskbuffer.Task({
-    name: 'runner-good-task',
-    taskFunction: async () => {
-      executionOrder.push('good');
-    },
-  });
-
-  await runner.start();
-  runner.addTask(badTask);
-  runner.addTask(goodTask);
-
-  // Wait for both tasks to be processed
-  await smartdelay.delayFor(500);
-  await runner.stop();
-
-  expect(executionOrder).toContain('bad');
-  expect(executionOrder).toContain('good');
-});
-
-// Test 8: BufferRunner handles errors without hanging
+// Test 7: BufferRunner handles errors without hanging
 tap.test('should handle BufferRunner errors without hanging', async () => {
   let callCount = 0;
   const bufferedTask = new taskbuffer.Task({

test/test.12.labels-and-events.ts

@@ -0,0 +1,249 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as taskbuffer from '../ts/index.js';
+import type { ITaskEvent } from '../ts/index.js';
+
+// ─── Labels ───
+
+tap.test('should accept labels in constructor', async () => {
+  const task = new taskbuffer.Task({
+    name: 'labelled-task',
+    taskFunction: async () => 'ok',
+    labels: { userId: 'u1', tenantId: 't1' },
+  });
+  expect(task.labels).toEqual({ userId: 'u1', tenantId: 't1' });
+});
+
+tap.test('should default labels to empty object', async () => {
+  const task = new taskbuffer.Task({
+    name: 'no-labels-task',
+    taskFunction: async () => 'ok',
+  });
+  expect(task.labels).toEqual({});
+});
+
+tap.test('setLabel / getLabel / removeLabel / hasLabel should work', async () => {
+  const task = new taskbuffer.Task({
+    name: 'label-helpers-task',
+    taskFunction: async () => 'ok',
+  });
+
+  task.setLabel('env', 'prod');
+  expect(task.getLabel('env')).toEqual('prod');
+  expect(task.hasLabel('env')).toBeTrue();
+  expect(task.hasLabel('env', 'prod')).toBeTrue();
+  expect(task.hasLabel('env', 'dev')).toBeFalse();
+  expect(task.hasLabel('missing')).toBeFalse();
+
+  const removed = task.removeLabel('env');
+  expect(removed).toBeTrue();
+  expect(task.getLabel('env')).toBeUndefined();
+
+  const removedAgain = task.removeLabel('env');
+  expect(removedAgain).toBeFalse();
+});
+
+tap.test('getMetadata() should include labels', async () => {
+  const task = new taskbuffer.Task({
+    name: 'metadata-labels-task',
+    taskFunction: async () => 'ok',
+    labels: { region: 'eu' },
+  });
+
+  const meta = task.getMetadata();
+  expect(meta.labels).toEqual({ region: 'eu' });
+
+  // Returned labels should be a copy
+  meta.labels!['region'] = 'us';
+  expect(task.labels['region']).toEqual('eu');
+});
+
+tap.test('TaskManager.getTasksByLabel should filter correctly', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const t1 = new taskbuffer.Task({
+    name: 'label-filter-1',
+    taskFunction: async () => 'ok',
+    labels: { userId: 'alice' },
+  });
+  const t2 = new taskbuffer.Task({
+    name: 'label-filter-2',
+    taskFunction: async () => 'ok',
+    labels: { userId: 'bob' },
+  });
+  const t3 = new taskbuffer.Task({
+    name: 'label-filter-3',
+    taskFunction: async () => 'ok',
+    labels: { userId: 'alice' },
+  });
+
+  manager.addTask(t1);
+  manager.addTask(t2);
+  manager.addTask(t3);
+
+  const aliceTasks = manager.getTasksByLabel('userId', 'alice');
+  expect(aliceTasks.length).toEqual(2);
+  expect(aliceTasks.map((t) => t.name).sort()).toEqual(['label-filter-1', 'label-filter-3']);
+
+  const bobMeta = manager.getTasksMetadataByLabel('userId', 'bob');
+  expect(bobMeta.length).toEqual(1);
+  expect(bobMeta[0].name).toEqual('label-filter-2');
+
+  await manager.stop();
+});
+
+// ─── Events ───
+
+tap.test('should emit started + completed on successful trigger', async () => {
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'event-success-task',
+    taskFunction: async () => 'ok',
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+  await task.trigger();
+
+  expect(events.length).toEqual(2);
+  expect(events[0].type).toEqual('started');
+  expect(events[1].type).toEqual('completed');
+  expect(events[0].task.name).toEqual('event-success-task');
+  expect(typeof events[0].timestamp).toEqual('number');
+});
+
+tap.test('should emit step events on notifyStep', async () => {
+  const steps = [
+    { name: 'build', description: 'Build artifacts', percentage: 50 },
+    { name: 'deploy', description: 'Deploy to prod', percentage: 50 },
+  ] as const;
+
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'step-event-task',
+    steps,
+    taskFunction: async () => {
+      task.notifyStep('build');
+      task.notifyStep('deploy');
+      return 'done';
+    },
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+  await task.trigger();
+
+  const stepEvents = events.filter((e) => e.type === 'step');
+  expect(stepEvents.length).toEqual(2);
+  expect(stepEvents[0].stepName).toEqual('build');
+  expect(stepEvents[1].stepName).toEqual('deploy');
+});
+
+tap.test('should emit started + failed on error', async () => {
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'event-fail-task',
+    taskFunction: async () => {
+      throw new Error('boom');
+    },
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+
+  try {
+    await task.trigger();
+  } catch {
+    // expected
+  }
+
+  expect(events.length).toEqual(2);
+  expect(events[0].type).toEqual('started');
+  expect(events[1].type).toEqual('failed');
+  expect(events[1].error).toEqual('boom');
+});
+
+tap.test('should emit failed via done.then path when catchErrors is true', async () => {
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'event-catch-fail-task',
+    catchErrors: true,
+    taskFunction: async () => {
+      throw new Error('swallowed');
+    },
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+  await task.trigger();
+
+  const types = events.map((e) => e.type);
+  expect(types).toContain('started');
+  expect(types).toContain('failed');
+});
+
+tap.test('TaskManager.taskSubject should aggregate events from added tasks', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const events: ITaskEvent[] = [];
+
+  const t1 = new taskbuffer.Task({
+    name: 'agg-task-1',
+    taskFunction: async () => 'a',
+  });
+  const t2 = new taskbuffer.Task({
+    name: 'agg-task-2',
+    taskFunction: async () => 'b',
+  });
+
+  manager.addTask(t1);
+  manager.addTask(t2);
+
+  manager.taskSubject.subscribe((e) => events.push(e));
+
+  await t1.trigger();
+  await t2.trigger();
+
+  const names = [...new Set(events.map((e) => e.task.name))];
+  expect(names.sort()).toEqual(['agg-task-1', 'agg-task-2']);
+  expect(events.filter((e) => e.type === 'started').length).toEqual(2);
+  expect(events.filter((e) => e.type === 'completed').length).toEqual(2);
+
+  await manager.stop();
+});
+
+tap.test('events should stop after removeTask', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const events: ITaskEvent[] = [];
+
+  const task = new taskbuffer.Task({
+    name: 'removable-event-task',
+    taskFunction: async () => 'ok',
+  });
+
+  manager.addTask(task);
+  manager.taskSubject.subscribe((e) => events.push(e));
+
+  await task.trigger();
+  const countBefore = events.length;
+  expect(countBefore).toBeGreaterThan(0);
+
+  manager.removeTask(task);
+
+  // Trigger again — events should NOT appear on manager subject
+  await task.trigger();
+  expect(events.length).toEqual(countBefore);
+
+  await manager.stop();
+});
+
+tap.test('event metadata snapshots should include correct labels', async () => {
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'labelled-event-task',
+    taskFunction: async () => 'ok',
+    labels: { team: 'platform' },
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+  await task.trigger();
+
+  for (const e of events) {
+    expect(e.task.labels).toEqual({ team: 'platform' });
+  }
+});
+
+export default tap.start();

test/test.13.constraints.ts

@@ -0,0 +1,391 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as taskbuffer from '../ts/index.js';
+import * as smartdelay from '@push.rocks/smartdelay';
+
+// Test 1: Task data property — typed data accessible
+tap.test('should have typed data property on task', async () => {
+  const task = new taskbuffer.Task<undefined, [], { domain: string; priority: number }>({
+    name: 'data-task',
+    data: { domain: 'example.com', priority: 1 },
+    taskFunction: async () => {},
+  });
+
+  expect(task.data.domain).toEqual('example.com');
+  expect(task.data.priority).toEqual(1);
+});
+
+// Test 2: Task data defaults to empty object
+tap.test('should default data to empty object when not provided', async () => {
+  const task = new taskbuffer.Task({
+    name: 'no-data-task',
+    taskFunction: async () => {},
+  });
+
+  expect(task.data).toBeTruthy();
+  expect(typeof task.data).toEqual('object');
+});
+
+// Test 3: No-constraint passthrough — behavior unchanged
+tap.test('should run tasks directly when no constraints are configured', async () => {
+  const manager = new taskbuffer.TaskManager();
+  let executed = false;
+
+  const task = new taskbuffer.Task({
+    name: 'passthrough-task',
+    taskFunction: async () => {
+      executed = true;
+      return 'done';
+    },
+  });
+
+  manager.addTask(task);
+  const result = await manager.triggerTaskByName('passthrough-task');
+  expect(executed).toBeTrue();
+  expect(result).toEqual('done');
+  await manager.stop();
+});
+
+// Test 4: Group concurrency — 3 tasks, max 2 concurrent, 3rd queues
+tap.test('should enforce group concurrency limit', async () => {
+  const manager = new taskbuffer.TaskManager();
+  let running = 0;
+  let maxRunning = 0;
+
+  const constraint = new taskbuffer.TaskConstraintGroup<{ group: string }>({
+    name: 'concurrency-test',
+    maxConcurrent: 2,
+    constraintKeyForTask: (task) =>
+      task.data.group === 'workers' ? 'workers' : null,
+  });
+  manager.addConstraintGroup(constraint);
+
+  const makeTask = (id: number) =>
+    new taskbuffer.Task<undefined, [], { group: string }>({
+      name: `worker-${id}`,
+      data: { group: 'workers' },
+      taskFunction: async () => {
+        running++;
+        maxRunning = Math.max(maxRunning, running);
+        await smartdelay.delayFor(200);
+        running--;
+      },
+    });
+
+  const t1 = makeTask(1);
+  const t2 = makeTask(2);
+  const t3 = makeTask(3);
+
+  manager.addTask(t1);
+  manager.addTask(t2);
+  manager.addTask(t3);
+
+  await Promise.all([
+    manager.triggerTaskConstrained(t1),
+    manager.triggerTaskConstrained(t2),
+    manager.triggerTaskConstrained(t3),
+  ]);
+
+  expect(maxRunning).toBeLessThanOrEqual(2);
+  await manager.stop();
+});
+
+// Test 5: Key-based mutual exclusion — same key sequential, different keys parallel
+tap.test('should enforce key-based mutual exclusion', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const log: string[] = [];
+
+  const constraint = new taskbuffer.TaskConstraintGroup<{ domain: string }>({
+    name: 'domain-mutex',
+    maxConcurrent: 1,
+    constraintKeyForTask: (task) => task.data.domain,
+  });
+  manager.addConstraintGroup(constraint);
+
+  const makeTask = (name: string, domain: string, delayMs: number) =>
+    new taskbuffer.Task<undefined, [], { domain: string }>({
+      name,
+      data: { domain },
+      taskFunction: async () => {
+        log.push(`${name}-start`);
+        await smartdelay.delayFor(delayMs);
+        log.push(`${name}-end`);
+      },
+    });
+
+  const taskA1 = makeTask('a1', 'a.com', 100);
+  const taskA2 = makeTask('a2', 'a.com', 100);
+  const taskB1 = makeTask('b1', 'b.com', 100);
+
+  manager.addTask(taskA1);
+  manager.addTask(taskA2);
+  manager.addTask(taskB1);
+
+  await Promise.all([
+    manager.triggerTaskConstrained(taskA1),
+    manager.triggerTaskConstrained(taskA2),
+    manager.triggerTaskConstrained(taskB1),
+  ]);
+
+  // a1 and a2 should be sequential (same key)
+  const a1EndIdx = log.indexOf('a1-end');
+  const a2StartIdx = log.indexOf('a2-start');
+  expect(a2StartIdx).toBeGreaterThanOrEqual(a1EndIdx);
+
+  // b1 should start concurrently with a1 (different key)
+  const a1StartIdx = log.indexOf('a1-start');
+  const b1StartIdx = log.indexOf('b1-start');
+  // Both should start before a1 ends
+  expect(b1StartIdx).toBeLessThan(a1EndIdx);
+
+  await manager.stop();
+});
+
+// Test 6: Cooldown enforcement
+tap.test('should enforce cooldown between task executions', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const timestamps: number[] = [];
+
+  const constraint = new taskbuffer.TaskConstraintGroup<{ key: string }>({
+    name: 'cooldown-test',
+    maxConcurrent: 1,
+    cooldownMs: 300,
+    constraintKeyForTask: (task) => task.data.key,
+  });
+  manager.addConstraintGroup(constraint);
+
+  const makeTask = (name: string) =>
+    new taskbuffer.Task<undefined, [], { key: string }>({
+      name,
+      data: { key: 'shared' },
+      taskFunction: async () => {
+        timestamps.push(Date.now());
+      },
+    });
+
+  const t1 = makeTask('cool-1');
+  const t2 = makeTask('cool-2');
+  const t3 = makeTask('cool-3');
+
+  manager.addTask(t1);
+  manager.addTask(t2);
+  manager.addTask(t3);
+
+  await Promise.all([
+    manager.triggerTaskConstrained(t1),
+    manager.triggerTaskConstrained(t2),
+    manager.triggerTaskConstrained(t3),
+  ]);
+
+  // Each execution should be at least ~300ms apart (with 200ms tolerance)
+  for (let i = 1; i < timestamps.length; i++) {
+    const gap = timestamps[i] - timestamps[i - 1];
+    expect(gap).toBeGreaterThanOrEqual(100); // 300ms cooldown minus tolerance
+  }
+
+  await manager.stop();
+});
+
+// Test 7: Multiple constraint groups on one task
+tap.test('should apply multiple constraint groups to one task', async () => {
+  const manager = new taskbuffer.TaskManager();
+  let running = 0;
+  let maxRunning = 0;
+
+  const globalConstraint = new taskbuffer.TaskConstraintGroup({
+    name: 'global',
+    maxConcurrent: 3,
+    constraintKeyForTask: () => 'all',
+  });
+
+  const groupConstraint = new taskbuffer.TaskConstraintGroup<{ group: string }>({
+    name: 'group',
+    maxConcurrent: 1,
+    constraintKeyForTask: (task) => task.data.group,
+  });
+
+  manager.addConstraintGroup(globalConstraint);
+  manager.addConstraintGroup(groupConstraint);
+
+  const makeTask = (name: string, group: string) =>
+    new taskbuffer.Task<undefined, [], { group: string }>({
+      name,
+      data: { group },
+      taskFunction: async () => {
+        running++;
+        maxRunning = Math.max(maxRunning, running);
+        await smartdelay.delayFor(100);
+        running--;
+      },
+    });
+
+  // Same group - should be serialized by group constraint
+  const t1 = makeTask('multi-1', 'A');
+  const t2 = makeTask('multi-2', 'A');
+
+  manager.addTask(t1);
+  manager.addTask(t2);
+
+  await Promise.all([
+    manager.triggerTaskConstrained(t1),
+    manager.triggerTaskConstrained(t2),
+  ]);
+
+  // With group maxConcurrent: 1, only 1 should run at a time
+  expect(maxRunning).toBeLessThanOrEqual(1);
+  await manager.stop();
+});
+
+// Test 8: Matcher returns null — task runs unconstrained
+tap.test('should run task unconstrained when matcher returns null', async () => {
+  const manager = new taskbuffer.TaskManager();
+
+  const constraint = new taskbuffer.TaskConstraintGroup<{ skip: boolean }>({
+    name: 'selective',
+    maxConcurrent: 1,
+    constraintKeyForTask: (task) => (task.data.skip ? null : 'constrained'),
+  });
+  manager.addConstraintGroup(constraint);
+
+  let unconstrained = false;
+  const task = new taskbuffer.Task<undefined, [], { skip: boolean }>({
+    name: 'skip-task',
+    data: { skip: true },
+    taskFunction: async () => {
+      unconstrained = true;
+    },
+  });
+
+  manager.addTask(task);
+  await manager.triggerTaskConstrained(task);
+  expect(unconstrained).toBeTrue();
+  await manager.stop();
+});
+
+// Test 9: Error handling — failed task releases slot, queue drains
+tap.test('should release slot and drain queue when task fails', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const log: string[] = [];
+
+  const constraint = new taskbuffer.TaskConstraintGroup<{ key: string }>({
+    name: 'error-drain',
+    maxConcurrent: 1,
+    constraintKeyForTask: (task) => task.data.key,
+  });
+  manager.addConstraintGroup(constraint);
+
+  const failTask = new taskbuffer.Task<undefined, [], { key: string }>({
+    name: 'fail-task',
+    data: { key: 'shared' },
+    catchErrors: true,
+    taskFunction: async () => {
+      log.push('fail');
+      throw new Error('intentional');
+    },
+  });
+
+  const successTask = new taskbuffer.Task<undefined, [], { key: string }>({
+    name: 'success-task',
+    data: { key: 'shared' },
+    taskFunction: async () => {
+      log.push('success');
+    },
+  });
+
+  manager.addTask(failTask);
+  manager.addTask(successTask);
+
+  await Promise.all([
+    manager.triggerTaskConstrained(failTask),
+    manager.triggerTaskConstrained(successTask),
+  ]);
+
+  expect(log).toContain('fail');
+  expect(log).toContain('success');
+  await manager.stop();
+});
+
+// Test 10: TaskManager integration — addConstraintGroup + triggerTaskByName
+tap.test('should route triggerTaskByName through constraints', async () => {
+  const manager = new taskbuffer.TaskManager();
+  let running = 0;
+  let maxRunning = 0;
+
+  const constraint = new taskbuffer.TaskConstraintGroup({
+    name: 'manager-integration',
+    maxConcurrent: 1,
+    constraintKeyForTask: () => 'all',
+  });
+  manager.addConstraintGroup(constraint);
+
+  const t1 = new taskbuffer.Task({
+    name: 'managed-1',
+    taskFunction: async () => {
+      running++;
+      maxRunning = Math.max(maxRunning, running);
+      await smartdelay.delayFor(100);
+      running--;
+    },
+  });
+
+  const t2 = new taskbuffer.Task({
+    name: 'managed-2',
+    taskFunction: async () => {
+      running++;
+      maxRunning = Math.max(maxRunning, running);
+      await smartdelay.delayFor(100);
+      running--;
+    },
+  });
+
+  manager.addTask(t1);
+  manager.addTask(t2);
+
+  await Promise.all([
+    manager.triggerTaskByName('managed-1'),
+    manager.triggerTaskByName('managed-2'),
+  ]);
+
+  expect(maxRunning).toBeLessThanOrEqual(1);
+  await manager.stop();
+});
+
+// Test 11: removeConstraintGroup removes by name
+tap.test('should remove a constraint group by name', async () => {
+  const manager = new taskbuffer.TaskManager();
+
+  const constraint = new taskbuffer.TaskConstraintGroup({
+    name: 'removable',
+    maxConcurrent: 1,
+    constraintKeyForTask: () => 'all',
+  });
+
+  manager.addConstraintGroup(constraint);
+  expect(manager.constraintGroups.length).toEqual(1);
+
+  manager.removeConstraintGroup('removable');
+  expect(manager.constraintGroups.length).toEqual(0);
+  await manager.stop();
+});
+
+// Test 12: TaskConstraintGroup reset clears state
+tap.test('should reset constraint group state', async () => {
+  const constraint = new taskbuffer.TaskConstraintGroup({
+    name: 'resettable',
+    maxConcurrent: 2,
+    cooldownMs: 1000,
+    constraintKeyForTask: () => 'key',
+  });
+
+  // Simulate usage
+  constraint.acquireSlot('key');
+  expect(constraint.getRunningCount('key')).toEqual(1);
+
+  constraint.releaseSlot('key');
+  expect(constraint.getCooldownRemaining('key')).toBeGreaterThan(0);
+
+  constraint.reset();
+  expect(constraint.getRunningCount('key')).toEqual(0);
+  expect(constraint.getCooldownRemaining('key')).toEqual(0);
+});
+
+export default tap.start();

test/test.2.taskchain.ts

@@ -36,12 +36,9 @@ tap.test('expect run tasks in sequence', async () => {
   });
   const testPromise = testTaskchain.trigger();
   await smartdelay.delayFor(2100);
-  // tslint:disable-next-line:no-unused-expression
   expect(task1Executed).toBeTrue();
-  // tslint:disable-next-line:no-unused-expression
   expect(task2Executed).toBeFalse();
   await smartdelay.delayFor(2100);
-  // tslint:disable-next-line:no-unused-expression
   expect(task2Executed).toBeTrue();
   await testPromise;
 });

test/test.4.taskmanager.ts

@@ -33,7 +33,6 @@ tap.test('should run the task as expected', async () => {
   );
   myTaskManager.start();
   await myTaskManager.triggerTaskByName('myTask');
-  // tslint:disable-next-line:no-unused-expression
   expect(referenceBoolean).toBeTrue();
 });
 

test/test.taskrunner.ts

@@ -1,34 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-
-import * as taskbuffer from '../ts/index.js';
-
-let testTaskRunner: taskbuffer.TaskRunner;
-
-tap.test('should create a valid taskrunner', async () => {
-  testTaskRunner = new taskbuffer.TaskRunner();
-  await testTaskRunner.start();
-});
-
-tap.test('should execute task when its scheduled', async (tools) => {
-  const done = tools.defer();
-  testTaskRunner.addTask(
-    new taskbuffer.Task({
-      taskFunction: async () => {
-        console.log('hi');
-      },
-    }),
-  );
-
-  testTaskRunner.addTask(
-    new taskbuffer.Task({
-      taskFunction: async () => {
-        console.log('there');
-        done.resolve();
-      },
-    }),
-  );
-
-  await done.promise;
-});
-
-tap.start();

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/taskbuffer',
-  version: '4.0.0',
+  version: '5.0.0',
   description: 'A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.'
 }

ts/index.ts

@@ -4,15 +4,15 @@ export { Taskchain } from './taskbuffer.classes.taskchain.js';
 export { Taskparallel } from './taskbuffer.classes.taskparallel.js';
 export { TaskManager } from './taskbuffer.classes.taskmanager.js';
 export { TaskOnce } from './taskbuffer.classes.taskonce.js';
-export { TaskRunner } from './taskbuffer.classes.taskrunner.js';
 export { TaskDebounced } from './taskbuffer.classes.taskdebounced.js';
+export { TaskConstraintGroup } from './taskbuffer.classes.taskconstraintgroup.js';
 
 // Task step system
 export { TaskStep } from './taskbuffer.classes.taskstep.js';
 export type { ITaskStep } from './taskbuffer.classes.taskstep.js';
 
 // Metadata interfaces
-export type { ITaskMetadata, ITaskExecutionReport, IScheduledTaskInfo } from './taskbuffer.interfaces.js';
+export type { ITaskMetadata, ITaskExecutionReport, IScheduledTaskInfo, ITaskEvent, TTaskEventType, ITaskConstraintGroupOptions } from './taskbuffer.interfaces.js';
 
 import * as distributedCoordination from './taskbuffer.classes.distributedcoordinator.js';
 export { distributedCoordination };

ts/taskbuffer.classes.bufferrunner.ts

@@ -6,7 +6,7 @@ export class BufferRunner {
   // initialize by default
   public bufferCounter: number = 0;
 
-  constructor(taskArg: Task<any>) {
+  constructor(taskArg: Task<any, any, any>) {
     this.task = taskArg;
   }
 

ts/taskbuffer.classes.cyclecounter.ts

@@ -9,7 +9,7 @@ export interface ICycleObject {
 export class CycleCounter {
   public task: Task;
   public cycleObjectArray: ICycleObject[] = [];
-  constructor(taskArg: Task<any>) {
+  constructor(taskArg: Task<any, any, any>) {
     this.task = taskArg;
   }
   public getPromiseForCycle(cycleCountArg: number) {

ts/taskbuffer.classes.task.ts

@@ -2,7 +2,7 @@ import * as plugins from './taskbuffer.plugins.js';
 import { BufferRunner } from './taskbuffer.classes.bufferrunner.js';
 import { CycleCounter } from './taskbuffer.classes.cyclecounter.js';
 import { TaskStep, type ITaskStep } from './taskbuffer.classes.taskstep.js';
-import type { ITaskMetadata } from './taskbuffer.interfaces.js';
+import type { ITaskMetadata, ITaskEvent, TTaskEventType } from './taskbuffer.interfaces.js';
 
 import { logger } from './taskbuffer.logging.js';
 
@@ -19,18 +19,18 @@ export type TPreOrAfterTaskFunction = () => Task<any>;
 // Type helper to extract step names from array
 export type StepNames<T> = T extends ReadonlyArray<{ name: infer N }> ? N : never;
 
-export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = []> {
+export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = [], TData extends Record<string, unknown> = Record<string, unknown>> {
   public static extractTask<T = undefined, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = []>(
-    preOrAfterTaskArg: Task<T, TSteps> | TPreOrAfterTaskFunction,
-  ): Task<T, TSteps> {
+    preOrAfterTaskArg: Task<T, TSteps, any> | TPreOrAfterTaskFunction,
+  ): Task<T, TSteps, any> {
     switch (true) {
       case !preOrAfterTaskArg:
         return null;
       case preOrAfterTaskArg instanceof Task:
-        return preOrAfterTaskArg as Task<T, TSteps>;
+        return preOrAfterTaskArg as Task<T, TSteps, any>;
       case typeof preOrAfterTaskArg === 'function':
         const taskFunction = preOrAfterTaskArg as TPreOrAfterTaskFunction;
-        return taskFunction() as unknown as Task<T, TSteps>;
+        return taskFunction() as unknown as Task<T, TSteps, any>;
       default:
         return null;
     }
@@ -42,7 +42,7 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
     return done.promise;
   };
 
-  public static isTask = (taskArg: Task<any>): boolean => {
+  public static isTask = (taskArg: Task<any, any, any>): boolean => {
     if (taskArg instanceof Task && typeof taskArg.taskFunction === 'function') {
       return true;
     } else {
@@ -51,8 +51,8 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
   };
 
   public static isTaskTouched<T = undefined, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = []>(
-    taskArg: Task<T, TSteps> | TPreOrAfterTaskFunction,
-    touchedTasksArray: Task<T, TSteps>[],
+    taskArg: Task<T, TSteps, any> | TPreOrAfterTaskFunction,
+    touchedTasksArray: Task<T, TSteps, any>[],
   ): boolean {
     const taskToCheck = Task.extractTask(taskArg);
     let result = false;
@@ -65,25 +65,16 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
   }
 
   public static runTask = async <T, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = []>(
-    taskArg: Task<T, TSteps> | TPreOrAfterTaskFunction,
-    optionsArg: { x?: any; touchedTasksArray?: Task<T, TSteps>[] },
+    taskArg: Task<T, TSteps, any> | TPreOrAfterTaskFunction,
+    optionsArg: { x?: any; touchedTasksArray?: Task<T, TSteps, any>[] },
   ) => {
     const taskToRun = Task.extractTask(taskArg);
     const done = plugins.smartpromise.defer();
 
-    // Wait for all blocking tasks to finish
-    for (const task of taskToRun.blockingTasks) {
-      await task.finished;
-    }
-
     if (!taskToRun.setupValue && taskToRun.taskSetup) {
       taskToRun.setupValue = await taskToRun.taskSetup();
     }
 
-    if (taskToRun.execDelay) {
-      await plugins.smartdelay.delayFor(taskToRun.execDelay);
-    }
-
     taskToRun.running = true;
     taskToRun.runCount++;
     taskToRun.lastRun = new Date();
@@ -91,6 +82,7 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
     // Reset steps and error state at the beginning of task execution
     taskToRun.resetSteps();
     taskToRun.lastError = undefined;
+    taskToRun.emitEvent('started');
 
     done.promise
       .then(async () => {
@@ -98,25 +90,11 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
 
         // Complete all steps when task finishes
         taskToRun.completeAllSteps();
-
-        // When the task has finished running, resolve the finished promise
-        taskToRun.resolveFinished();
-
-        // Create a new finished promise for the next run
-        taskToRun.finished = new Promise((resolve) => {
-          taskToRun.resolveFinished = resolve;
-        });
+        taskToRun.emitEvent(taskToRun.lastError ? 'failed' : 'completed');
       })
       .catch((err) => {
         taskToRun.running = false;
-
-        // Resolve finished so blocking dependants don't hang
-        taskToRun.resolveFinished();
-
-        // Create a new finished promise for the next run
-        taskToRun.finished = new Promise((resolve) => {
-          taskToRun.resolveFinished = resolve;
-        });
+        taskToRun.emitEvent('failed', { error: err instanceof Error ? err.message : String(err) });
       });
 
     const options = {
@@ -124,7 +102,7 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
       ...optionsArg,
     };
     const x = options.x;
-    const touchedTasksArray: Task<T, TSteps>[] = options.touchedTasksArray;
+    const touchedTasksArray: Task<T, TSteps, any>[] = options.touchedTasksArray;
 
     touchedTasksArray.push(taskToRun);
 
@@ -195,18 +173,12 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
   public cronJob: plugins.smarttime.CronJob;
 
   public bufferMax: number;
-  public execDelay: number;
   public timeout: number;
 
-  public preTask: Task<T, any> | TPreOrAfterTaskFunction;
-  public afterTask: Task<T, any> | TPreOrAfterTaskFunction;
+  public data: TData;
 
-  // Add a list to store the blocking tasks
-  public blockingTasks: Task[] = [];
-
-  // Add a promise that will resolve when the task has finished
-  private finished: Promise<void>;
-  private resolveFinished: () => void;
+  public preTask: Task<T, any, any> | TPreOrAfterTaskFunction;
+  public afterTask: Task<T, any, any> | TPreOrAfterTaskFunction;
 
   public running: boolean = false;
   public bufferRunner = new BufferRunner(this);
@@ -218,6 +190,8 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
   public catchErrors: boolean = false;
   public lastError?: Error;
   public errorCount: number = 0;
+  public labels: Record<string, string> = {};
+  public readonly eventSubject = new plugins.smartrx.rxjs.Subject<ITaskEvent>();
 
   public get idle() {
     return !this.running;
@@ -227,6 +201,38 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
     this.lastError = undefined;
   }
 
+  public setLabel(key: string, value: string): void {
+    this.labels[key] = value;
+  }
+
+  public getLabel(key: string): string | undefined {
+    return this.labels[key];
+  }
+
+  public removeLabel(key: string): boolean {
+    if (key in this.labels) {
+      delete this.labels[key];
+      return true;
+    }
+    return false;
+  }
+
+  public hasLabel(key: string, value?: string): boolean {
+    if (value !== undefined) {
+      return this.labels[key] === value;
+    }
+    return key in this.labels;
+  }
+
+  private emitEvent(type: TTaskEventType, extra?: Partial<ITaskEvent>): void {
+    this.eventSubject.next({
+      type,
+      task: this.getMetadata(),
+      timestamp: Date.now(),
+      ...extra,
+    });
+  }
+
   public taskSetup: ITaskSetupFunction<T>;
   public setupValue: T;
 
@@ -238,25 +244,27 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
 
   constructor(optionsArg: {
     taskFunction: ITaskFunction<T>;
-    preTask?: Task<T, any> | TPreOrAfterTaskFunction;
-    afterTask?: Task<T, any> | TPreOrAfterTaskFunction;
+    preTask?: Task<T, any, any> | TPreOrAfterTaskFunction;
+    afterTask?: Task<T, any, any> | TPreOrAfterTaskFunction;
     buffered?: boolean;
     bufferMax?: number;
-    execDelay?: number;
     name?: string;
+    data?: TData;
     taskSetup?: ITaskSetupFunction<T>;
     steps?: TSteps;
     catchErrors?: boolean;
+    labels?: Record<string, string>;
   }) {
     this.taskFunction = optionsArg.taskFunction;
     this.preTask = optionsArg.preTask;
     this.afterTask = optionsArg.afterTask;
     this.buffered = optionsArg.buffered;
     this.bufferMax = optionsArg.bufferMax;
-    this.execDelay = optionsArg.execDelay;
     this.name = optionsArg.name;
+    this.data = optionsArg.data ?? ({} as TData);
     this.taskSetup = optionsArg.taskSetup;
     this.catchErrors = optionsArg.catchErrors ?? false;
+    this.labels = optionsArg.labels ? { ...optionsArg.labels } : {};
 
     // Initialize steps if provided
     if (optionsArg.steps) {
@@ -270,11 +278,6 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
         this.steps.set(stepConfig.name, step);
       }
     }
-
-    // Create the finished promise
-    this.finished = new Promise((resolve) => {
-      this.resolveFinished = resolve;
-    });
   }
 
   public trigger(x?: any): Promise<any> {
@@ -309,8 +312,8 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
     if (step) {
       step.start();
       this.currentStepName = stepName as string;
-      
-      // Emit event for frontend updates (could be enhanced with event emitter)
+      this.emitEvent('step', { stepName: stepName as string });
+
       if (this.name) {
         logger.log('info', `Task ${this.name}: Starting step "${stepName}" - ${step.description}`);
       }
@@ -369,6 +372,7 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
       cronSchedule: this.cronJob?.cronExpression,
       lastError: this.lastError?.message,
       errorCount: this.errorCount,
+      labels: { ...this.labels },
     };
   }
 

ts/taskbuffer.classes.taskconstraintgroup.ts

@@ -0,0 +1,80 @@
+import type { Task } from './taskbuffer.classes.task.js';
+import type { ITaskConstraintGroupOptions } from './taskbuffer.interfaces.js';
+
+export class TaskConstraintGroup<TData extends Record<string, unknown> = Record<string, unknown>> {
+  public name: string;
+  public maxConcurrent: number;
+  public cooldownMs: number;
+  private constraintKeyForTask: (task: Task<any, any, TData>) => string | null | undefined;
+
+  private runningCounts = new Map<string, number>();
+  private lastCompletionTimes = new Map<string, number>();
+
+  constructor(options: ITaskConstraintGroupOptions<TData>) {
+    this.name = options.name;
+    this.constraintKeyForTask = options.constraintKeyForTask;
+    this.maxConcurrent = options.maxConcurrent ?? Infinity;
+    this.cooldownMs = options.cooldownMs ?? 0;
+  }
+
+  public getConstraintKey(task: Task<any, any, TData>): string | null {
+    const key = this.constraintKeyForTask(task);
+    return key ?? null;
+  }
+
+  public canRun(subGroupKey: string): boolean {
+    const running = this.runningCounts.get(subGroupKey) ?? 0;
+    if (running >= this.maxConcurrent) {
+      return false;
+    }
+
+    if (this.cooldownMs > 0) {
+      const lastCompletion = this.lastCompletionTimes.get(subGroupKey);
+      if (lastCompletion !== undefined) {
+        const elapsed = Date.now() - lastCompletion;
+        if (elapsed < this.cooldownMs) {
+          return false;
+        }
+      }
+    }
+
+    return true;
+  }
+
+  public acquireSlot(subGroupKey: string): void {
+    const current = this.runningCounts.get(subGroupKey) ?? 0;
+    this.runningCounts.set(subGroupKey, current + 1);
+  }
+
+  public releaseSlot(subGroupKey: string): void {
+    const current = this.runningCounts.get(subGroupKey) ?? 0;
+    const next = Math.max(0, current - 1);
+    if (next === 0) {
+      this.runningCounts.delete(subGroupKey);
+    } else {
+      this.runningCounts.set(subGroupKey, next);
+    }
+    this.lastCompletionTimes.set(subGroupKey, Date.now());
+  }
+
+  public getCooldownRemaining(subGroupKey: string): number {
+    if (this.cooldownMs <= 0) {
+      return 0;
+    }
+    const lastCompletion = this.lastCompletionTimes.get(subGroupKey);
+    if (lastCompletion === undefined) {
+      return 0;
+    }
+    const elapsed = Date.now() - lastCompletion;
+    return Math.max(0, this.cooldownMs - elapsed);
+  }
+
+  public getRunningCount(subGroupKey: string): number {
+    return this.runningCounts.get(subGroupKey) ?? 0;
+  }
+
+  public reset(): void {
+    this.runningCounts.clear();
+    this.lastCompletionTimes.clear();
+  }
+}

ts/taskbuffer.classes.taskmanager.ts

@@ -1,10 +1,11 @@
 import * as plugins from './taskbuffer.plugins.js';
 import { Task } from './taskbuffer.classes.task.js';
+import { TaskConstraintGroup } from './taskbuffer.classes.taskconstraintgroup.js';
 import {
   AbstractDistributedCoordinator,
   type IDistributedTaskRequestResult,
 } from './taskbuffer.classes.distributedcoordinator.js';
-import type { ITaskMetadata, ITaskExecutionReport, IScheduledTaskInfo } from './taskbuffer.interfaces.js';
+import type { ITaskMetadata, ITaskExecutionReport, IScheduledTaskInfo, ITaskEvent, IConstrainedTaskEntry } from './taskbuffer.interfaces.js';
 import { logger } from './taskbuffer.logging.js';
 
 export interface ICronJob {
@@ -19,42 +20,175 @@ export interface ITaskManagerConstructorOptions {
 
 export class TaskManager {
   public randomId = plugins.smartunique.shortId();
-  public taskMap = new plugins.lik.ObjectMap<Task<any, any>>();
+  public taskMap = new plugins.lik.ObjectMap<Task<any, any, any>>();
+  public readonly taskSubject = new plugins.smartrx.rxjs.Subject<ITaskEvent>();
+  private taskSubscriptions = new Map<Task<any, any, any>, plugins.smartrx.rxjs.Subscription>();
   private cronJobManager = new plugins.smarttime.CronManager();
   public options: ITaskManagerConstructorOptions = {
     distributedCoordinator: null,
   };
 
+  // Constraint system
+  public constraintGroups: TaskConstraintGroup<any>[] = [];
+  private constraintQueue: IConstrainedTaskEntry[] = [];
+  private drainTimer: ReturnType<typeof setTimeout> | null = null;
+
   constructor(options: ITaskManagerConstructorOptions = {}) {
     this.options = Object.assign(this.options, options);
   }
 
-  public getTaskByName(taskName: string): Task<any, any> {
+  public getTaskByName(taskName: string): Task<any, any, any> {
     return this.taskMap.findSync((task) => task.name === taskName);
   }
 
-  public addTask(task: Task<any, any>): void {
+  public addTask(task: Task<any, any, any>): void {
     if (!task.name) {
       throw new Error('Task must have a name to be added to taskManager');
     }
     this.taskMap.add(task);
+    const subscription = task.eventSubject.subscribe((event) => {
+      this.taskSubject.next(event);
+    });
+    this.taskSubscriptions.set(task, subscription);
   }
 
-  public addAndScheduleTask(task: Task<any, any>, cronString: string) {
+  public removeTask(task: Task<any, any, any>): void {
+    this.taskMap.remove(task);
+    const subscription = this.taskSubscriptions.get(task);
+    if (subscription) {
+      subscription.unsubscribe();
+      this.taskSubscriptions.delete(task);
+    }
+  }
+
+  public addAndScheduleTask(task: Task<any, any, any>, cronString: string) {
     this.addTask(task);
     this.scheduleTaskByName(task.name, cronString);
   }
 
+  // Constraint group management
+  public addConstraintGroup(group: TaskConstraintGroup<any>): void {
+    this.constraintGroups.push(group);
+  }
+
+  public removeConstraintGroup(name: string): void {
+    this.constraintGroups = this.constraintGroups.filter((g) => g.name !== name);
+  }
+
+  // Core constraint evaluation
+  public async triggerTaskConstrained(task: Task<any, any, any>, input?: any): Promise<any> {
+    // Gather applicable constraints
+    const applicableGroups: Array<{ group: TaskConstraintGroup<any>; key: string }> = [];
+    for (const group of this.constraintGroups) {
+      const key = group.getConstraintKey(task);
+      if (key !== null) {
+        applicableGroups.push({ group, key });
+      }
+    }
+
+    // No constraints apply → trigger directly
+    if (applicableGroups.length === 0) {
+      return task.trigger(input);
+    }
+
+    // Check if all constraints allow running
+    const allCanRun = applicableGroups.every(({ group, key }) => group.canRun(key));
+    if (allCanRun) {
+      return this.executeWithConstraintTracking(task, input, applicableGroups);
+    }
+
+    // Blocked → enqueue with deferred promise
+    const deferred = plugins.smartpromise.defer<any>();
+    this.constraintQueue.push({ task, input, deferred });
+    return deferred.promise;
+  }
+
+  private async executeWithConstraintTracking(
+    task: Task<any, any, any>,
+    input: any,
+    groups: Array<{ group: TaskConstraintGroup<any>; key: string }>,
+  ): Promise<any> {
+    // Acquire slots
+    for (const { group, key } of groups) {
+      group.acquireSlot(key);
+    }
+
+    try {
+      return await task.trigger(input);
+    } finally {
+      // Release slots
+      for (const { group, key } of groups) {
+        group.releaseSlot(key);
+      }
+      this.drainConstraintQueue();
+    }
+  }
+
+  private drainConstraintQueue(): void {
+    let shortestCooldown = Infinity;
+    const stillQueued: IConstrainedTaskEntry[] = [];
+
+    for (const entry of this.constraintQueue) {
+      const applicableGroups: Array<{ group: TaskConstraintGroup<any>; key: string }> = [];
+      for (const group of this.constraintGroups) {
+        const key = group.getConstraintKey(entry.task);
+        if (key !== null) {
+          applicableGroups.push({ group, key });
+        }
+      }
+
+      // No constraints apply anymore (group removed?) → run directly
+      if (applicableGroups.length === 0) {
+        entry.task.trigger(entry.input).then(
+          (result) => entry.deferred.resolve(result),
+          (err) => entry.deferred.reject(err),
+        );
+        continue;
+      }
+
+      const allCanRun = applicableGroups.every(({ group, key }) => group.canRun(key));
+      if (allCanRun) {
+        this.executeWithConstraintTracking(entry.task, entry.input, applicableGroups).then(
+          (result) => entry.deferred.resolve(result),
+          (err) => entry.deferred.reject(err),
+        );
+      } else {
+        stillQueued.push(entry);
+        // Track shortest cooldown for timer scheduling
+        for (const { group, key } of applicableGroups) {
+          const remaining = group.getCooldownRemaining(key);
+          if (remaining > 0 && remaining < shortestCooldown) {
+            shortestCooldown = remaining;
+          }
+        }
+      }
+    }
+
+    this.constraintQueue = stillQueued;
+
+    // Schedule next drain if there are cooldown-blocked entries
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
+    if (stillQueued.length > 0 && shortestCooldown < Infinity) {
+      this.drainTimer = setTimeout(() => {
+        this.drainTimer = null;
+        this.drainConstraintQueue();
+      }, shortestCooldown + 1);
+    }
+  }
+
   public async triggerTaskByName(taskName: string): Promise<any> {
     const taskToTrigger = this.getTaskByName(taskName);
     if (!taskToTrigger) {
       throw new Error(`No task with the name ${taskName} found.`);
     }
-    return taskToTrigger.trigger();
+    return this.triggerTaskConstrained(taskToTrigger);
   }
 
-  public async triggerTask(task: Task<any, any>) {
-    return task.trigger();
+  public async triggerTask(task: Task<any, any, any>) {
+    return this.triggerTaskConstrained(task);
   }
 
   public scheduleTaskByName(taskName: string, cronString: string) {
@@ -65,7 +199,7 @@ export class TaskManager {
     this.handleTaskScheduling(taskToSchedule, cronString);
   }
 
-  private handleTaskScheduling(task: Task<any, any>, cronString: string) {
+  private handleTaskScheduling(task: Task<any, any, any>, cronString: string) {
     const cronJob = this.cronJobManager.addCronjob(
       cronString,
       async (triggerTime: number) => {
@@ -83,7 +217,7 @@ export class TaskManager {
           }
         }
         try {
-          await task.trigger();
+          await this.triggerTaskConstrained(task);
         } catch (err) {
           logger.log('error', `TaskManager: scheduled task "${task.name || 'unnamed'}" failed: ${err instanceof Error ? err.message : String(err)}`);
         }
@@ -92,7 +226,7 @@ export class TaskManager {
     task.cronJob = cronJob;
   }
 
-  private logTaskState(task: Task<any, any>) {
+  private logTaskState(task: Task<any, any, any>) {
     logger.log('info', `Taskbuffer schedule triggered task >>${task.name}<<`);
     const bufferState = task.buffered
       ? `buffered with max ${task.bufferMax} buffered calls`
@@ -101,7 +235,7 @@ export class TaskManager {
   }
 
   private async performDistributedConsultation(
-    task: Task<any, any>,
+    task: Task<any, any, any>,
     triggerTime: number,
   ): Promise<IDistributedTaskRequestResult> {
     logger.log('info', 'Found a distributed coordinator, performing consultation.');
@@ -129,7 +263,7 @@ export class TaskManager {
     }
   }
 
-  public async descheduleTask(task: Task<any, any>) {
+  public async descheduleTask(task: Task<any, any, any>) {
     await this.descheduleTaskByName(task.name);
   }
 
@@ -150,6 +284,14 @@ export class TaskManager {
     if (this.options.distributedCoordinator) {
       await this.options.distributedCoordinator.stop();
     }
+    for (const [, subscription] of this.taskSubscriptions) {
+      subscription.unsubscribe();
+    }
+    this.taskSubscriptions.clear();
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
   }
 
   // Get metadata for a specific task
@@ -167,7 +309,7 @@ export class TaskManager {
   // Get scheduled tasks with their schedules and next run times
   public getScheduledTasks(): IScheduledTaskInfo[] {
     const scheduledTasks: IScheduledTaskInfo[] = [];
-    
+
     for (const task of this.taskMap.getArray()) {
       if (task.cronJob) {
         scheduledTasks.push({
@@ -180,7 +322,7 @@ export class TaskManager {
         });
       }
     }
-    
+
     return scheduledTasks;
   }
 
@@ -194,13 +336,21 @@ export class TaskManager {
       }))
       .sort((a, b) => a.nextRun.getTime() - b.nextRun.getTime())
       .slice(0, limit);
-    
+
     return scheduledRuns;
   }
 
+  public getTasksByLabel(key: string, value: string): Task<any, any, any>[] {
+    return this.taskMap.getArray().filter(task => task.labels[key] === value);
+  }
+
+  public getTasksMetadataByLabel(key: string, value: string): ITaskMetadata[] {
+    return this.getTasksByLabel(key, value).map(task => task.getMetadata());
+  }
+
   // Add, execute, and remove a task while collecting metadata
   public async addExecuteRemoveTask<T, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }>>(
-    task: Task<T, TSteps>,
+    task: Task<T, TSteps, any>,
     options?: {
       schedule?: string;
       trackProgress?: boolean;
@@ -208,19 +358,18 @@ export class TaskManager {
   ): Promise<ITaskExecutionReport> {
     // Add task to manager
     this.addTask(task);
-    
+
     // Optionally schedule it
     if (options?.schedule) {
       this.scheduleTaskByName(task.name!, options.schedule);
     }
-    
+
     const startTime = Date.now();
-    const progressUpdates: Array<{ stepName: string; timestamp: number }> = [];
-    
+
     try {
-      // Execute the task
-      const result = await task.trigger();
-      
+      // Execute the task through constraints
+      const result = await this.triggerTaskConstrained(task);
+
       // Collect execution report
       const report: ITaskExecutionReport = {
         taskName: task.name || 'unnamed',
@@ -234,15 +383,15 @@ export class TaskManager {
         progress: task.getProgress(),
         result,
       };
-      
+
       // Remove task from manager
-      this.taskMap.remove(task);
-      
+      this.removeTask(task);
+
       // Deschedule if it was scheduled
       if (options?.schedule && task.name) {
         this.descheduleTaskByName(task.name);
       }
-      
+
       return report;
     } catch (error) {
       // Create error report
@@ -258,15 +407,15 @@ export class TaskManager {
         progress: task.getProgress(),
         error: error as Error,
       };
-      
+
       // Remove task from manager even on error
-      this.taskMap.remove(task);
-      
+      this.removeTask(task);
+
       // Deschedule if it was scheduled
       if (options?.schedule && task.name) {
         this.descheduleTaskByName(task.name);
       }
-      
+
       throw errorReport;
     }
   }

ts/taskbuffer.classes.taskrunner.ts

@@ -1,69 +0,0 @@
-import * as plugins from './taskbuffer.plugins.js';
-
-import { Task } from './taskbuffer.classes.task.js';
-import { logger } from './taskbuffer.logging.js';
-
-export class TaskRunner {
-  public maxParallelJobs: number = 1;
-  public status: 'stopped' | 'running' = 'stopped';
-  public runningTasks: plugins.lik.ObjectMap<Task> =
-    new plugins.lik.ObjectMap<Task>();
-  public queuedTasks: Task[] = [];
-
-  constructor() {
-    this.runningTasks.eventSubject.subscribe(async (eventArg) => {
-      this.checkExecution();
-    });
-  }
-
-  /**
-   * adds a task to the queue
-   */
-  public addTask(taskArg: Task) {
-    this.queuedTasks.push(taskArg);
-    this.checkExecution();
-  }
-
-  /**
-   * set amount of parallel tasks
-   * be careful, you might lose dependability of tasks
-   */
-  public setMaxParallelJobs(maxParallelJobsArg: number) {
-    this.maxParallelJobs = maxParallelJobsArg;
-  }
-
-  /**
-   * starts the task queue
-   */
-  public async start() {
-    this.status = 'running';
-  }
-
-  /**
-   * checks whether execution is on point
-   */
-  public async checkExecution() {
-    if (
-      this.runningTasks.getArray().length < this.maxParallelJobs &&
-      this.status === 'running' &&
-      this.queuedTasks.length > 0
-    ) {
-      const nextJob = this.queuedTasks.shift();
-      this.runningTasks.add(nextJob);
-      try {
-        await nextJob.trigger();
-      } catch (err) {
-        logger.log('error', `TaskRunner: task "${nextJob.name || 'unnamed'}" failed: ${err instanceof Error ? err.message : String(err)}`);
-      }
-      this.runningTasks.remove(nextJob);
-      this.checkExecution();
-    }
-  }
-
-  /**
-   * stops the task queue
-   */
-  public async stop() {
-    this.status = 'stopped';
-  }
-}

ts/taskbuffer.interfaces.ts

@@ -1,4 +1,18 @@
 import type { ITaskStep } from './taskbuffer.classes.taskstep.js';
+import type { Task } from './taskbuffer.classes.task.js';
+
+export interface ITaskConstraintGroupOptions<TData extends Record<string, unknown> = Record<string, unknown>> {
+  name: string;
+  constraintKeyForTask: (task: Task<any, any, TData>) => string | null | undefined;
+  maxConcurrent?: number;  // default: Infinity
+  cooldownMs?: number;     // default: 0
+}
+
+export interface IConstrainedTaskEntry {
+  task: Task<any, any, any>;
+  input: any;
+  deferred: import('@push.rocks/smartpromise').Deferred<any>;
+}
 
 export interface ITaskMetadata {
   name: string;
@@ -17,6 +31,7 @@ export interface ITaskMetadata {
   timeout?: number;
   lastError?: string;
   errorCount?: number;
+  labels?: Record<string, string>;
 }
 
 export interface ITaskExecutionReport {
@@ -38,4 +53,14 @@ export interface IScheduledTaskInfo {
   lastRun?: Date;
   steps?: ITaskStep[];
   metadata?: ITaskMetadata;
+}
+
+export type TTaskEventType = 'started' | 'step' | 'completed' | 'failed';
+
+export interface ITaskEvent {
+  type: TTaskEventType;
+  task: ITaskMetadata;
+  timestamp: number;
+  stepName?: string;   // present when type === 'step'
+  error?: string;      // present when type === 'failed'
 }

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/taskbuffer',
-  version: '4.0.0',
+  version: '5.0.0',
   description: 'A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.'
 }

ts_web/taskbuffer-dashboard.ts

@@ -8,20 +8,20 @@ import type { TaskManager, ITaskMetadata, IScheduledTaskInfo } from '../ts/index
 export class TaskbufferDashboard extends DeesElement {
   // Properties
   @property({ type: Object })
-  public taskManager: TaskManager | null = null;
+  accessor taskManager: TaskManager | null = null;
 
   @property({ type: Number })
-  public refreshInterval: number = 1000; // milliseconds
+  accessor refreshInterval: number = 1000; // milliseconds
 
   // Internal state
   @state()
-  private tasks: ITaskMetadata[] = [];
+  accessor tasks: ITaskMetadata[] = [];
 
   @state()
-  private scheduledTasks: IScheduledTaskInfo[] = [];
+  accessor scheduledTasks: IScheduledTaskInfo[] = [];
 
   @state()
-  private isRunning: boolean = false;
+  accessor isRunning: boolean = false;
 
   private refreshTimer: any;