v6.1.1

fix(tests): improve buffered task tests: add chain, concurrency and queue behavior tests
v6.1.0
2026-02-15 21:56:39 +00:00 · 2026-02-15 21:56:39 +00:00 · 2026-02-15 21:51:55 +00:00 · 2026-02-15 21:51:55 +00:00 · 2026-02-15 21:08:38 +00:00 · 2026-02-15 21:08:38 +00:00
30 changed files with 5927 additions and 3477 deletions
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,102 @@
 # Changelog

+## 2026-02-15 - 6.1.1 - fix(tests)
+improve buffered task tests: add chain, concurrency and queue behavior tests
+
+- Replace tools.delayFor with @push.rocks/smartdelay for more deterministic timing in tests
+- Add tests for afterTask chaining, bufferMax concurrency, queued-run limits, and re-trigger behavior
+- Rename tasks to descriptive names and fix afterTask chaining order to avoid circular references
+- Change test runner invocation to export default tap.start() instead of calling tap.start() directly
+
+## 2026-02-15 - 6.1.0 - feat(taskbuffer)
+add sliding-window rate limiting and result-sharing to TaskConstraintGroup and integrate with TaskManager
+
+- Added IRateLimitConfig and TResultSharingMode types and exported them from the public index
+- TaskConstraintGroup: added rateLimit and resultSharingMode options, internal completion timestamp tracking, and last-result storage
+- TaskConstraintGroup: new helpers - pruneCompletionTimestamps, getRateLimitDelay, getNextAvailableDelay, recordResult, getLastResult, hasResultSharing
+- TaskConstraintGroup: rate-limit logic enforces maxPerWindow (counts running + completions) and composes with cooldown/maxConcurrent
+- TaskManager: records successful task results to constraint groups and resolves queued entries immediately when a shared result exists
+- TaskManager: queue drain now considers unified next-available delay (cooldown + rate limit) when scheduling retries
+- Documentation updated: README and hints with usage examples for sliding-window rate limiting and result sharing
+- Comprehensive tests added for rate limiting, concurrency interaction, and result-sharing behavior
+
+## 2026-02-15 - 6.0.1 - fix(taskbuffer)
+no changes to commit
+
+- Git diff shows no changes
+- package.json current version is 6.0.0; no version bump required
+
+## 2026-02-15 - 6.0.0 - BREAKING CHANGE(constraints)
+make TaskConstraintGroup constraint matcher input-aware and add shouldExecute pre-execution hook
+
+- Rename ITaskConstraintGroupOptions.constraintKeyForTask -> constraintKeyForExecution(task, input?) and update TaskConstraintGroup.getConstraintKey signature
+- Add optional shouldExecute(task, input?) hook; TaskManager checks shouldExecute before immediate runs, after acquiring slots, and when draining the constraint queue (queued tasks are skipped when shouldExecute returns false)
+- Export ITaskExecution type and store constraintKeys on queued entries (IConstrainedTaskEntry.constraintKeys)
+- Documentation and tests updated to demonstrate input-aware constraint keys and shouldExecute pruning
+
+## 2026-02-15 - 5.0.1 - fix(tests)
+add and tighten constraint-related tests covering return values, error propagation, concurrency, cooldown timing, and constraint removal
+
+- Tightened cooldown timing assertion from >=100ms to >=250ms to reflect 300ms cooldown with 50ms tolerance.
+- Added tests for queued task return values, error propagation when catchErrors is false, and error swallowing behavior when catchErrors is true.
+- Added concurrency and cooldown interaction tests to ensure maxConcurrent is respected and batch timing is correct.
+- Added test verifying removing a constraint group unblocks queued tasks and drain behavior completes correctly.
+
+## 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.
+
+- Introduce catchErrors option on Task (default: false) — previously errors were swallowed by default
+- Tasks now set lastError and increment errorCount when failures occur; clearError() added to reset error state
+- getMetadata() now reports status 'failed' and includes lastError and errorCount
+- Task.run flow updated to reset error state at start, log errors, and either swallow or rethrow based on catchErrors
+- BufferRunner, TaskRunner, Taskchain, Taskparallel, TaskDebounced and TaskManager updated to handle errors, avoid hanging promises, and use logger instead of console
+- Added comprehensive tests (test/test.11.errorhandling.ts) and readme hints documenting the new error-handling behavior (v3.6.0+)
+- npmextra.json updated for @git.zone/cli and release registries
+
 ## 2025-12-04 - 3.5.0 - feat(core)
 Add debounced tasks and step-based progress tracking; upgrade deps and improve dashboard and scheduling

--- a/license.md
+++ b/license.md
--- a/npmextra.json
+++ b/npmextra.json
@@ -1,10 +1,5 @@
 {
-  "npmci": {
-    "npmGlobalTools": [],
-    "npmAccessLevel": "public",
-    "npmRegistryUrl": "registry.npmjs.org"
-  },
-  "gitzone": {
+  "@git.zone/cli": {
    "projectType": "npm",
    "module": {
      "githost": "code.foss.global",
@@ -25,9 +20,20 @@
        "debounced tasks",
        "distributed coordination"
      ]
+    },
+    "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"
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": [],
+    "npmRegistryUrl": "registry.npmjs.org"
  }
-}
+}
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@push.rocks/taskbuffer",
-  "version": "3.5.0",
+  "version": "6.1.1",
  "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/**/*",
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -1 +1,110 @@
- 
+# 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, constraintKeyForExecution, maxConcurrent?, cooldownMs?, shouldExecute?, rateLimit?, resultSharingMode? })`
+- `constraintKeyForExecution(task, input?)` returns a string key (constraint applies) or `null` (skip). Receives both task and runtime input.
+- `shouldExecute(task, input?)` — optional pre-execution check. Returns `false` to skip (deferred resolves `undefined`). Can be async.
+- `maxConcurrent` (default: `Infinity`) — max concurrent tasks per key
+- `cooldownMs` (default: `0`) — minimum ms gap between completions per key
+- `rateLimit` (optional) — `{ maxPerWindow: number, windowMs: number }` sliding window rate limiter. Counts both running + completed tasks in window.
+- `resultSharingMode` (default: `'none'`) — `'none'` | `'share-latest'`. When `'share-latest'`, queued tasks for the same key resolve with the first task's result without executing.
+- Methods: `getConstraintKey(task, input?)`, `checkShouldExecute(task, input?)`, `canRun(key)`, `acquireSlot(key)`, `releaseSlot(key)`, `getCooldownRemaining(key)`, `getRateLimitDelay(key)`, `getNextAvailableDelay(key)`, `getRunningCount(key)`, `recordResult(key, result)`, `getLastResult(key)`, `hasResultSharing()`, `reset()`
+- `ITaskExecution<TData>` type exported from index — `{ task, input }` tuple
+
+### Rate Limiting (v6.1.0+)
+- Sliding window rate limiter: `rateLimit: { maxPerWindow: N, windowMs: ms }`
+- Counts running + completed tasks against the window cap
+- Per-key independence: saturating key A doesn't block key B
+- Composable with `maxConcurrent` and `cooldownMs`
+- `getNextAvailableDelay(key)` returns `Math.max(cooldownRemaining, rateLimitDelay)` — unified "how long until I can run" answer
+- Drain timer auto-schedules based on shortest delay across all constraints
+
+### Result Sharing (v6.1.0+)
+- `resultSharingMode: 'share-latest'` — queued tasks for the same key get the first task's result without executing
+- Only successful results are shared (errors from `catchErrors: true` or thrown errors are NOT shared)
+- `shouldExecute` is NOT called for shared results (the task's purpose was already fulfilled)
+- `lastResults` persists until `reset()` — for time-bounded sharing, use `shouldExecute` to control staleness
+- Composable with rate limiting: rate-limited waiters get shared result without waiting for the window
+
+### 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`, `IRateLimitConfig`, `TResultSharingMode` types
+
+## 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, BufferRunner, TaskDebounced, TaskManager) have proper error propagation/handling
+- `console.log` calls replaced with `logger.log()` throughout
+
+## 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`, `*.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
--- a/readme.md
+++ b/readme.md
--- a/test/test.10.webcomponent.chromium.ts
+++ b/test/test.10.webcomponent.chromium.ts
--- a/test/test.11.errorhandling.ts
+++ b/test/test.11.errorhandling.ts
@@ -0,0 +1,332 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as taskbuffer from '../ts/index.js';
+import * as smartdelay from '@push.rocks/smartdelay';
+
+// Test 1: Default task rejects on error (catchErrors: false)
+tap.test('should reject when taskFunction throws (default catchErrors: false)', async () => {
+  const failingTask = new taskbuffer.Task({
+    name: 'failing-task-default',
+    taskFunction: async () => {
+      throw new Error('intentional failure');
+    },
+  });
+
+  let didReject = false;
+  try {
+    await failingTask.trigger();
+  } catch (err) {
+    didReject = true;
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toEqual('intentional failure');
+  }
+  expect(didReject).toBeTrue();
+});
+
+// Test 2: Task with catchErrors: true resolves on error
+tap.test('should resolve with undefined when catchErrors is true', async () => {
+  const failingTask = new taskbuffer.Task({
+    name: 'failing-task-catch',
+    catchErrors: true,
+    taskFunction: async () => {
+      throw new Error('swallowed failure');
+    },
+  });
+
+  const result = await failingTask.trigger();
+  expect(result).toBeUndefined();
+});
+
+// Test 3: lastError and errorCount are set after failure
+tap.test('should set lastError and errorCount after failure', async () => {
+  const failingTask = new taskbuffer.Task({
+    name: 'failing-task-state',
+    catchErrors: true,
+    taskFunction: async () => {
+      throw new Error('tracked failure');
+    },
+  });
+
+  await failingTask.trigger();
+  expect(failingTask.lastError).toBeInstanceOf(Error);
+  expect(failingTask.lastError.message).toEqual('tracked failure');
+  expect(failingTask.errorCount).toEqual(1);
+
+  // Run again to verify errorCount increments
+  await failingTask.trigger();
+  expect(failingTask.errorCount).toEqual(2);
+});
+
+// Test 4: Error state resets on successful re-run
+tap.test('should reset lastError on successful re-run', async () => {
+  let shouldFail = true;
+  const task = new taskbuffer.Task({
+    name: 'intermittent-task',
+    catchErrors: true,
+    taskFunction: async () => {
+      if (shouldFail) {
+        throw new Error('first run fails');
+      }
+      return 'success';
+    },
+  });
+
+  // First run: fail
+  await task.trigger();
+  expect(task.lastError).toBeInstanceOf(Error);
+  expect(task.errorCount).toEqual(1);
+
+  // Second run: succeed
+  shouldFail = false;
+  const result = await task.trigger();
+  expect(result).toEqual('success');
+  expect(task.lastError).toBeUndefined();
+  // errorCount should still be 1 since the second run succeeded
+  expect(task.errorCount).toEqual(1);
+});
+
+// Test 5: Taskchain rejects when a child task throws
+tap.test('should reject Taskchain when a child task throws', async () => {
+  const goodTask = new taskbuffer.Task({
+    name: 'good-chain-task',
+    taskFunction: async () => 'ok',
+  });
+  const badTask = new taskbuffer.Task({
+    name: 'bad-chain-task',
+    taskFunction: async () => {
+      throw new Error('chain failure');
+    },
+  });
+
+  const chain = new taskbuffer.Taskchain({
+    name: 'test-chain',
+    taskArray: [goodTask, badTask],
+  });
+
+  let didReject = false;
+  try {
+    await chain.trigger();
+  } catch (err) {
+    didReject = true;
+  }
+  expect(didReject).toBeTrue();
+});
+
+// Test 6: Taskparallel rejects when a child task throws
+tap.test('should reject Taskparallel when a child task throws', async () => {
+  const goodTask = new taskbuffer.Task({
+    name: 'good-parallel-task',
+    taskFunction: async () => 'ok',
+  });
+  const badTask = new taskbuffer.Task({
+    name: 'bad-parallel-task',
+    taskFunction: async () => {
+      throw new Error('parallel failure');
+    },
+  });
+
+  const parallel = new taskbuffer.Taskparallel({
+    taskArray: [goodTask, badTask],
+  });
+
+  let didReject = false;
+  try {
+    await parallel.trigger();
+  } catch (err) {
+    didReject = true;
+  }
+  expect(didReject).toBeTrue();
+});
+
+// Test 7: BufferRunner handles errors without hanging
+tap.test('should handle BufferRunner errors without hanging', async () => {
+  let callCount = 0;
+  const bufferedTask = new taskbuffer.Task({
+    name: 'buffer-error-task',
+    buffered: true,
+    bufferMax: 3,
+    catchErrors: true,
+    taskFunction: async () => {
+      callCount++;
+      throw new Error('buffer failure');
+    },
+  });
+
+  await bufferedTask.trigger();
+  // The task should have executed and not hung
+  expect(callCount).toBeGreaterThan(0);
+});
+
+// Test 9: clearError() resets error state
+tap.test('should reset error state with clearError()', async () => {
+  const task = new taskbuffer.Task({
+    name: 'clearable-task',
+    catchErrors: true,
+    taskFunction: async () => {
+      throw new Error('to be cleared');
+    },
+  });
+
+  await task.trigger();
+  expect(task.lastError).toBeInstanceOf(Error);
+
+  task.clearError();
+  expect(task.lastError).toBeUndefined();
+  // errorCount should remain unchanged
+  expect(task.errorCount).toEqual(1);
+});
+
+// Test 10: getMetadata() reflects error state
+tap.test('should reflect error state in getMetadata()', async () => {
+  const task = new taskbuffer.Task({
+    name: 'metadata-error-task',
+    catchErrors: true,
+    taskFunction: async () => {
+      throw new Error('metadata failure');
+    },
+  });
+
+  // Before any run
+  let metadata = task.getMetadata();
+  expect(metadata.status).toEqual('idle');
+  expect(metadata.errorCount).toEqual(0);
+
+  // After failing
+  await task.trigger();
+  metadata = task.getMetadata();
+  expect(metadata.status).toEqual('failed');
+  expect(metadata.lastError).toEqual('metadata failure');
+  expect(metadata.errorCount).toEqual(1);
+});
+
+// Test 11: TaskChain error includes task name and index context
+tap.test('should include task name and index in TaskChain error message', async () => {
+  const goodTask = new taskbuffer.Task({
+    name: 'chain-step-ok',
+    taskFunction: async () => 'ok',
+  });
+  const badTask = new taskbuffer.Task({
+    name: 'chain-step-fail',
+    taskFunction: async () => {
+      throw new Error('step exploded');
+    },
+  });
+
+  const chain = new taskbuffer.Taskchain({
+    name: 'context-chain',
+    taskArray: [goodTask, badTask],
+  });
+
+  let caughtError: Error | null = null;
+  try {
+    await chain.trigger();
+  } catch (err) {
+    caughtError = err as Error;
+  }
+  expect(caughtError).toBeInstanceOf(Error);
+  expect(caughtError.message).toInclude('context-chain');
+  expect(caughtError.message).toInclude('chain-step-fail');
+  expect(caughtError.message).toInclude('index 1');
+  expect((caughtError as any).cause).toBeInstanceOf(Error);
+  expect(((caughtError as any).cause as Error).message).toEqual('step exploded');
+});
+
+// Test 12: BufferRunner error propagation with catchErrors: false
+tap.test('should reject buffered task when catchErrors is false', async () => {
+  const bufferedTask = new taskbuffer.Task({
+    name: 'buffer-reject-task',
+    buffered: true,
+    bufferMax: 3,
+    catchErrors: false,
+    taskFunction: async () => {
+      throw new Error('buffer reject failure');
+    },
+  });
+
+  let didReject = false;
+  try {
+    await bufferedTask.trigger();
+  } catch (err) {
+    didReject = true;
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toEqual('buffer reject failure');
+  }
+  expect(didReject).toBeTrue();
+});
+
+// Test 13: Taskchain removeTask removes and returns true
+tap.test('should remove a task from Taskchain', async () => {
+  const task1 = new taskbuffer.Task({
+    name: 'removable-1',
+    taskFunction: async () => 'a',
+  });
+  const task2 = new taskbuffer.Task({
+    name: 'removable-2',
+    taskFunction: async () => 'b',
+  });
+
+  const chain = new taskbuffer.Taskchain({
+    name: 'remove-chain',
+    taskArray: [task1, task2],
+  });
+
+  const removed = chain.removeTask(task1);
+  expect(removed).toBeTrue();
+  expect(chain.taskArray.length).toEqual(1);
+  expect(chain.taskArray[0] === task2).toBeTrue();
+});
+
+// Test 14: Taskchain removeTask returns false for unknown task
+tap.test('should return false when removing a task not in Taskchain', async () => {
+  const task1 = new taskbuffer.Task({
+    name: 'existing',
+    taskFunction: async () => 'a',
+  });
+  const unknown = new taskbuffer.Task({
+    name: 'unknown',
+    taskFunction: async () => 'b',
+  });
+
+  const chain = new taskbuffer.Taskchain({
+    name: 'remove-false-chain',
+    taskArray: [task1],
+  });
+
+  const removed = chain.removeTask(unknown);
+  expect(removed).toBeFalse();
+  expect(chain.taskArray.length).toEqual(1);
+});
+
+// Test 15: Taskchain shiftTask returns first task and shortens array
+tap.test('should shift the first task from Taskchain', async () => {
+  const task1 = new taskbuffer.Task({
+    name: 'shift-1',
+    taskFunction: async () => 'a',
+  });
+  const task2 = new taskbuffer.Task({
+    name: 'shift-2',
+    taskFunction: async () => 'b',
+  });
+
+  const chain = new taskbuffer.Taskchain({
+    name: 'shift-chain',
+    taskArray: [task1, task2],
+  });
+
+  const shifted = chain.shiftTask();
+  expect(shifted === task1).toBeTrue();
+  expect(chain.taskArray.length).toEqual(1);
+  expect(chain.taskArray[0] === task2).toBeTrue();
+});
+
+// Test 16: Taskchain shiftTask returns undefined on empty array
+tap.test('should return undefined when shifting from empty Taskchain', async () => {
+  const chain = new taskbuffer.Taskchain({
+    name: 'empty-shift-chain',
+    taskArray: [],
+  });
+
+  const shifted = chain.shiftTask();
+  expect(shifted).toBeUndefined();
+});
+
+export default tap.start();
--- a/test/test.12.labels-and-events.ts
+++ b/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();
--- a/test/test.13.constraints.ts
+++ b/test/test.13.constraints.ts
--- a/test/test.2.taskchain.ts
+++ b/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;
 });
--- a/test/test.4.taskmanager.ts
+++ b/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();
 });

--- a/test/test.8.bufferedrun.ts
+++ b/test/test.8.bufferedrun.ts
@@ -1,52 +1,151 @@
 import { tap, expect } from '@git.zone/tstest/tapbundle';

 import * as taskbuffer from '../ts/index.js';
+import * as smartdelay from '@push.rocks/smartdelay';

-let counter1 = 0;
-let counter2 = 0;
-let counter3 = 0;
+// Test 1: Basic buffered execution with afterTask chain
+tap.test('should run buffered tasks with afterTask chain', async () => {
+  let counter1 = 0;
+  let counter2 = 0;
+  let counter3 = 0;

-tap.test('should run buffered', async (tools) => {
-  const task = new taskbuffer.Task({
-    name: 'a buffered task',
-    taskFunction: async () => {
-      counter1++;
-      await tools.delayFor(2000);
-      console.log(`task 1 ran ${counter1} times`);
-    },
-    buffered: true,
-    bufferMax: 1,
-    afterTask: () => {
-      return task2;
-    },
-  });
-  const task2 = new taskbuffer.Task({
-    name: 'a buffered task',
-    taskFunction: async () => {
-      counter2++;
-      await tools.delayFor(2000);
-      console.log(`task2 ran ${counter2} times`);
-    },
-    buffered: true,
-    bufferMax: 1,
-    afterTask: () => {
-      return task3;
-    },
-  });
  const task3 = new taskbuffer.Task({
-    name: 'a buffered task',
+    name: 'buffered-chain-3',
    taskFunction: async () => {
      counter3++;
-      await tools.delayFor(2000);
-      console.log(`task3 ran ${counter3} times`);
+      await smartdelay.delayFor(50);
    },
    buffered: true,
    bufferMax: 1,
  });
-  while (counter1 < 10) {
-    await tools.delayFor(5000);
-    task.trigger();
+
+  const task2 = new taskbuffer.Task({
+    name: 'buffered-chain-2',
+    taskFunction: async () => {
+      counter2++;
+      await smartdelay.delayFor(50);
+    },
+    buffered: true,
+    bufferMax: 1,
+    afterTask: () => task3,
+  });
+
+  const task1 = new taskbuffer.Task({
+    name: 'buffered-chain-1',
+    taskFunction: async () => {
+      counter1++;
+      await smartdelay.delayFor(50);
+    },
+    buffered: true,
+    bufferMax: 1,
+    afterTask: () => task2,
+  });
+
+  // Trigger 3 times with enough spacing for the chain to complete
+  for (let i = 0; i < 3; i++) {
+    task1.trigger();
+    await smartdelay.delayFor(250); // enough for chain of 3 x 50ms tasks
  }
+
+  // Wait for final chain to finish
+  await smartdelay.delayFor(500);
+
+  // Each task in the chain should have run at least once
+  expect(counter1).toBeGreaterThanOrEqual(1);
+  expect(counter2).toBeGreaterThanOrEqual(1);
+  expect(counter3).toBeGreaterThanOrEqual(1);
+
+  // afterTask chain means task2 count should match task1 (each trigger chains)
+  expect(counter2).toEqual(counter1);
+  expect(counter3).toEqual(counter1);
 });

-tap.start();
+// Test 2: bufferMax limits concurrent buffered executions
+tap.test('should respect bufferMax for concurrent buffered calls', async () => {
+  let running = 0;
+  let maxRunning = 0;
+  let totalRuns = 0;
+
+  const task = new taskbuffer.Task({
+    name: 'buffer-max-test',
+    taskFunction: async () => {
+      running++;
+      maxRunning = Math.max(maxRunning, running);
+      totalRuns++;
+      await smartdelay.delayFor(100);
+      running--;
+    },
+    buffered: true,
+    bufferMax: 2,
+  });
+
+  // Fire many triggers rapidly — only bufferMax should run concurrently
+  for (let i = 0; i < 10; i++) {
+    task.trigger();
+  }
+
+  // Wait for all buffered executions to complete
+  await smartdelay.delayFor(1000);
+
+  expect(maxRunning).toBeLessThanOrEqual(2);
+  expect(totalRuns).toBeGreaterThanOrEqual(1);
+});
+
+// Test 3: bufferMax limits how many runs are queued during execution
+tap.test('should limit queued runs to bufferMax during execution', async () => {
+  let runCount = 0;
+
+  const task = new taskbuffer.Task({
+    name: 'buffer-queue-test',
+    taskFunction: async () => {
+      runCount++;
+      await smartdelay.delayFor(100);
+    },
+    buffered: true,
+    bufferMax: 2,
+  });
+
+  // Rapid-fire 5 triggers — bufferMax:2 means counter caps at 2
+  // so only 2 runs will happen (the initial run + 1 buffered rerun)
+  task.trigger();
+  task.trigger();
+  task.trigger();
+  task.trigger();
+  task.trigger();
+
+  await smartdelay.delayFor(500);
+
+  expect(runCount).toEqual(2);
+});
+
+// Test 4: Triggers spaced after completion queue new runs
+tap.test('should re-trigger after previous buffered run completes', async () => {
+  let runCount = 0;
+
+  const task = new taskbuffer.Task({
+    name: 'retrigger-test',
+    taskFunction: async () => {
+      runCount++;
+      await smartdelay.delayFor(50);
+    },
+    buffered: true,
+    bufferMax: 1,
+  });
+
+  // First trigger starts execution
+  task.trigger();
+  // Wait for it to complete
+  await smartdelay.delayFor(100);
+
+  // Second trigger starts a new execution (task is now idle)
+  task.trigger();
+  await smartdelay.delayFor(100);
+
+  // Third trigger
+  task.trigger();
+  await smartdelay.delayFor(100);
+
+  expect(runCount).toEqual(3);
+});
+
+export default tap.start();
--- a/test/test.9.steps.ts
+++ b/test/test.9.steps.ts
@@ -147,7 +147,7 @@ tap.test('Task should provide complete metadata', async () => {
  
  // Get metadata after execution
  metadata = task.getMetadata();
-  expect(metadata.status).toEqual('idle');
+  expect(metadata.status).toEqual('completed');
  expect(metadata.runCount).toEqual(1);
  expect(metadata.currentProgress).toEqual(100);
 });
--- a/test/test.taskrunner.ts
+++ b/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();
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@push.rocks/taskbuffer',
-  version: '3.5.0',
+  version: '6.1.1',
  description: 'A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.'
 }
--- a/ts/index.ts
+++ b/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, ITaskExecution, IRateLimitConfig, TResultSharingMode } from './taskbuffer.interfaces.js';

 import * as distributedCoordination from './taskbuffer.classes.distributedcoordinator.js';
 export { distributedCoordination };
--- a/ts/taskbuffer.classes.bufferrunner.ts
+++ b/ts/taskbuffer.classes.bufferrunner.ts
@@ -1,11 +1,12 @@
 import { Task } from './taskbuffer.classes.task.js';
+import { logger } from './taskbuffer.logging.js';

 export class BufferRunner {
  public task: Task;
  // initialize by default
  public bufferCounter: number = 0;

-  constructor(taskArg: Task<any>) {
+  constructor(taskArg: Task<any, any, any>) {
    this.task = taskArg;
  }

@@ -24,9 +25,19 @@ export class BufferRunner {
  private async _run(x: any) {
    this.task.running = true;
    while (this.bufferCounter > 0) {
-      const result = await Task.runTask(this.task, { x: x });
-      this.bufferCounter--;
-      this.task.cycleCounter.informOfCycle(result);
+      try {
+        const result = await Task.runTask(this.task, { x: x });
+        this.bufferCounter--;
+        this.task.cycleCounter.informOfCycle(result);
+      } catch (err) {
+        logger.log('error', `BufferRunner: task "${this.task.name || 'unnamed'}" failed: ${err instanceof Error ? err.message : String(err)}`);
+        this.bufferCounter--;
+        if (this.task.catchErrors) {
+          this.task.cycleCounter.informOfCycle(undefined);
+        } else {
+          this.task.cycleCounter.informOfCycleError(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
    }
    this.task.running = false;
  }
--- a/ts/taskbuffer.classes.cyclecounter.ts
+++ b/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) {
@@ -33,4 +33,16 @@ export class CycleCounter {
    });
    this.cycleObjectArray = newCycleObjectArray;
  }
+  public informOfCycleError(err: Error) {
+    const newCycleObjectArray: ICycleObject[] = [];
+    this.cycleObjectArray.forEach((cycleObjectArg) => {
+      cycleObjectArg.cycleCounter--;
+      if (cycleObjectArg.cycleCounter <= 0) {
+        cycleObjectArg.deferred.reject(err);
+      } else {
+        newCycleObjectArray.push(cycleObjectArg);
+      }
+    });
+    this.cycleObjectArray = newCycleObjectArray;
+  }
 }
--- a/ts/taskbuffer.classes.task.ts
+++ b/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,53 +65,44 @@ 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();
-    
-    // Reset steps at the beginning of task execution
+
+    // Reset steps and error state at the beginning of task execution
    taskToRun.resetSteps();
+    taskToRun.lastError = undefined;
+    taskToRun.emitEvent('started');

-    done.promise.then(async () => {
-      taskToRun.running = false;
-      
-      // Complete all steps when task finishes
-      taskToRun.completeAllSteps();
+    done.promise
+      .then(async () => {
+        taskToRun.running = false;

-      // 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;
+        // Complete all steps when task finishes
+        taskToRun.completeAllSteps();
+        taskToRun.emitEvent(taskToRun.lastError ? 'failed' : 'completed');
+      })
+      .catch((err) => {
+        taskToRun.running = false;
+        taskToRun.emitEvent('failed', { error: err instanceof Error ? err.message : String(err) });
      });
-    });

    const options = {
      ...{ x: undefined, touchedTasksArray: [] },
      ...optionsArg,
    };
    const x = options.x;
-    const touchedTasksArray: Task<T, TSteps>[] = options.touchedTasksArray;
+    const touchedTasksArray: Task<T, TSteps, any>[] = options.touchedTasksArray;

    touchedTasksArray.push(taskToRun);

@@ -133,7 +124,13 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
        try {
          return await taskToRun.taskFunction(x, taskToRun.setupValue);
        } catch (e) {
-          console.log(e);
+          taskToRun.lastError = e instanceof Error ? e : new Error(String(e));
+          taskToRun.errorCount++;
+          logger.log('error', `Task "${taskToRun.name || 'unnamed'}" failed: ${taskToRun.lastError.message}`);
+          if (taskToRun.catchErrors) {
+            return undefined;
+          }
+          throw e;
        }
      })
      .then((x) => {
@@ -155,10 +152,18 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
        done.resolve(x);
      })
      .catch((err) => {
-        console.log(err);
+        done.reject(err);
      });
    localDeferred.resolve();
-    return await done.promise;
+
+    try {
+      return await done.promise;
+    } catch (err) {
+      if (taskToRun.catchErrors) {
+        return undefined;
+      }
+      throw err;
+    }
  };

  public name: string;
@@ -168,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);
@@ -187,10 +186,53 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
  public lastRun?: Date;
  public runCount: number = 0;

+  // Error handling
+  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;
  }

+  public clearError(): void {
+    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;

@@ -202,23 +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) {
@@ -232,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> {
@@ -271,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}`);
      }
@@ -306,10 +347,21 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de

  // Get task metadata
  public getMetadata(): ITaskMetadata {
+    let status: 'idle' | 'running' | 'completed' | 'failed';
+    if (this.running) {
+      status = 'running';
+    } else if (this.lastError) {
+      status = 'failed';
+    } else if (this.runCount > 0) {
+      status = 'completed';
+    } else {
+      status = 'idle';
+    }
+
    return {
      name: this.name || 'unnamed',
      version: this.version,
-      status: this.running ? 'running' : 'idle',
+      status,
      steps: this.getStepsMetadata(),
      currentStep: this.currentStepName,
      currentProgress: this.getProgress(),
@@ -318,6 +370,9 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
      bufferMax: this.bufferMax,
      timeout: this.timeout,
      cronSchedule: this.cronJob?.cronExpression,
+      lastError: this.lastError?.message,
+      errorCount: this.errorCount,
+      labels: { ...this.labels },
    };
  }

--- a/ts/taskbuffer.classes.taskchain.ts
+++ b/ts/taskbuffer.classes.taskchain.ts
@@ -27,18 +27,20 @@ export class Taskchain extends Task {
          let taskCounter = 0; // counter for iterating async over the taskArray
          const iterateTasks = (x: any) => {
            if (typeof this.taskArray[taskCounter] !== 'undefined') {
-              console.log(
-                this.name + ' running: Task' + this.taskArray[taskCounter].name,
-              );
+              logger.log('info', `${this.name} running: Task ${this.taskArray[taskCounter].name}`);
              this.taskArray[taskCounter].trigger(x).then((x) => {
                logger.log('info', this.taskArray[taskCounter].name);
                taskCounter++;
                iterateTasks(x);
+              }).catch((err) => {
+                const chainError = new Error(
+                  `Taskchain "${this.name}": task "${this.taskArray[taskCounter].name || 'unnamed'}" (index ${taskCounter}) failed: ${err instanceof Error ? err.message : String(err)}`
+                );
+                (chainError as any).cause = err;
+                done.reject(chainError);
              });
            } else {
-              console.log(
-                'Taskchain "' + this.name + '" completed successfully',
-              );
+              logger.log('info', `Taskchain "${this.name}" completed successfully`);
              done.resolve(x);
            }
          };
@@ -53,10 +55,15 @@ export class Taskchain extends Task {
  addTask(taskArg: Task) {
    this.taskArray.push(taskArg);
  }
-  removeTask(taskArg: Task) {
-    // TODO:
+  removeTask(taskArg: Task): boolean {
+    const index = this.taskArray.indexOf(taskArg);
+    if (index === -1) {
+      return false;
+    }
+    this.taskArray.splice(index, 1);
+    return true;
  }
-  shiftTask() {
-    // TODO:
+  shiftTask(): Task | undefined {
+    return this.taskArray.shift();
  }
 }
--- a/ts/taskbuffer.classes.taskconstraintgroup.ts
+++ b/ts/taskbuffer.classes.taskconstraintgroup.ts
@@ -0,0 +1,164 @@
+import type { Task } from './taskbuffer.classes.task.js';
+import type { ITaskConstraintGroupOptions, IRateLimitConfig, TResultSharingMode } from './taskbuffer.interfaces.js';
+
+export class TaskConstraintGroup<TData extends Record<string, unknown> = Record<string, unknown>> {
+  public name: string;
+  public maxConcurrent: number;
+  public cooldownMs: number;
+  public rateLimit: IRateLimitConfig | null;
+  public resultSharingMode: TResultSharingMode;
+  private constraintKeyForExecution: (task: Task<any, any, TData>, input?: any) => string | null | undefined;
+  private shouldExecuteFn?: (task: Task<any, any, TData>, input?: any) => boolean | Promise<boolean>;
+
+  private runningCounts = new Map<string, number>();
+  private lastCompletionTimes = new Map<string, number>();
+  private completionTimestamps = new Map<string, number[]>();
+  private lastResults = new Map<string, { result: any; timestamp: number }>();
+
+  constructor(options: ITaskConstraintGroupOptions<TData>) {
+    this.name = options.name;
+    this.constraintKeyForExecution = options.constraintKeyForExecution;
+    this.maxConcurrent = options.maxConcurrent ?? Infinity;
+    this.cooldownMs = options.cooldownMs ?? 0;
+    this.shouldExecuteFn = options.shouldExecute;
+    this.rateLimit = options.rateLimit ?? null;
+    this.resultSharingMode = options.resultSharingMode ?? 'none';
+  }
+
+  public getConstraintKey(task: Task<any, any, TData>, input?: any): string | null {
+    const key = this.constraintKeyForExecution(task, input);
+    return key ?? null;
+  }
+
+  public async checkShouldExecute(task: Task<any, any, TData>, input?: any): Promise<boolean> {
+    if (!this.shouldExecuteFn) {
+      return true;
+    }
+    return this.shouldExecuteFn(task, input);
+  }
+
+  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;
+        }
+      }
+    }
+
+    if (this.rateLimit) {
+      this.pruneCompletionTimestamps(subGroupKey);
+      const timestamps = this.completionTimestamps.get(subGroupKey);
+      const completedInWindow = timestamps ? timestamps.length : 0;
+      const running = this.runningCounts.get(subGroupKey) ?? 0;
+      if (completedInWindow + running >= this.rateLimit.maxPerWindow) {
+        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());
+
+    if (this.rateLimit) {
+      const timestamps = this.completionTimestamps.get(subGroupKey) ?? [];
+      timestamps.push(Date.now());
+      this.completionTimestamps.set(subGroupKey, timestamps);
+    }
+  }
+
+  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;
+  }
+
+  // Rate limit helpers
+  private pruneCompletionTimestamps(subGroupKey: string): void {
+    const timestamps = this.completionTimestamps.get(subGroupKey);
+    if (!timestamps || !this.rateLimit) return;
+    const cutoff = Date.now() - this.rateLimit.windowMs;
+    let i = 0;
+    while (i < timestamps.length && timestamps[i] <= cutoff) {
+      i++;
+    }
+    if (i > 0) {
+      timestamps.splice(0, i);
+    }
+  }
+
+  public getRateLimitDelay(subGroupKey: string): number {
+    if (!this.rateLimit) return 0;
+    this.pruneCompletionTimestamps(subGroupKey);
+    const timestamps = this.completionTimestamps.get(subGroupKey);
+    const completedInWindow = timestamps ? timestamps.length : 0;
+    const running = this.runningCounts.get(subGroupKey) ?? 0;
+    if (completedInWindow + running < this.rateLimit.maxPerWindow) {
+      return 0;
+    }
+    // If only running tasks fill the window (no completions yet), we can't compute a delay
+    if (!timestamps || timestamps.length === 0) {
+      return 1; // minimal delay; drain will re-check after running tasks complete
+    }
+    // The oldest timestamp in the window determines when a slot opens
+    const oldestInWindow = timestamps[0];
+    const expiry = oldestInWindow + this.rateLimit.windowMs;
+    return Math.max(0, expiry - Date.now());
+  }
+
+  public getNextAvailableDelay(subGroupKey: string): number {
+    return Math.max(this.getCooldownRemaining(subGroupKey), this.getRateLimitDelay(subGroupKey));
+  }
+
+  // Result sharing helpers
+  public recordResult(subGroupKey: string, result: any): void {
+    if (this.resultSharingMode === 'none') return;
+    this.lastResults.set(subGroupKey, { result, timestamp: Date.now() });
+  }
+
+  public getLastResult(subGroupKey: string): { result: any; timestamp: number } | undefined {
+    return this.lastResults.get(subGroupKey);
+  }
+
+  public hasResultSharing(): boolean {
+    return this.resultSharingMode !== 'none';
+  }
+
+  public reset(): void {
+    this.runningCounts.clear();
+    this.lastCompletionTimes.clear();
+    this.completionTimestamps.clear();
+    this.lastResults.clear();
+  }
+}
--- a/ts/taskbuffer.classes.taskdebounced.ts
+++ b/ts/taskbuffer.classes.taskdebounced.ts
@@ -1,6 +1,7 @@
 import * as plugins from './taskbuffer.plugins.js';

 import { Task, type ITaskFunction } from './taskbuffer.classes.task.js';
+import { logger } from './taskbuffer.logging.js';

 export class TaskDebounced<T = unknown> extends Task {
  private _debouncedTaskFunction: ITaskFunction;
@@ -22,8 +23,17 @@ export class TaskDebounced<T = unknown> extends Task {
      .pipe(
        plugins.smartrx.rxjs.ops.debounceTime(optionsArg.debounceTimeInMillis),
      )
-      .subscribe((x) => {
-        this.taskFunction(x);
+      .subscribe({
+        next: async (x) => {
+          try {
+            await this.taskFunction(x);
+          } catch (err) {
+            logger.log('error', `TaskDebounced "${this.name || 'unnamed'}" failed: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        },
+        error: (err) => {
+          logger.log('error', `TaskDebounced "${this.name || 'unnamed'}" observable error: ${err instanceof Error ? err.message : String(err)}`);
+        },
      });
  }
 }
--- a/ts/taskbuffer.classes.taskmanager.ts
+++ b/ts/taskbuffer.classes.taskmanager.ts
@@ -1,10 +1,12 @@
 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 {
  cronString: string;
@@ -18,42 +20,230 @@ 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, input);
+      if (key !== null) {
+        applicableGroups.push({ group, key });
+      }
+    }
+
+    // No constraints apply → check shouldExecute then trigger directly
+    if (applicableGroups.length === 0) {
+      const shouldRun = await this.checkAllShouldExecute(task, input);
+      if (!shouldRun) {
+        return undefined;
+      }
+      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 and cached constraint keys
+    const deferred = plugins.smartpromise.defer<any>();
+    const constraintKeys = new Map<string, string>();
+    for (const { group, key } of applicableGroups) {
+      constraintKeys.set(group.name, key);
+    }
+    this.constraintQueue.push({ task, input, deferred, constraintKeys });
+    return deferred.promise;
+  }
+
+  private async checkAllShouldExecute(task: Task<any, any, any>, input?: any): Promise<boolean> {
+    for (const group of this.constraintGroups) {
+      const shouldRun = await group.checkShouldExecute(task, input);
+      if (!shouldRun) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  private async executeWithConstraintTracking(
+    task: Task<any, any, any>,
+    input: any,
+    groups: Array<{ group: TaskConstraintGroup<any>; key: string }>,
+  ): Promise<any> {
+    // Acquire slots synchronously to prevent race conditions
+    for (const { group, key } of groups) {
+      group.acquireSlot(key);
+    }
+
+    // Check shouldExecute after acquiring slots
+    const shouldRun = await this.checkAllShouldExecute(task, input);
+    if (!shouldRun) {
+      // Release slots and drain queue
+      for (const { group, key } of groups) {
+        group.releaseSlot(key);
+      }
+      this.drainConstraintQueue();
+      return undefined;
+    }
+
+    try {
+      const result = await task.trigger(input);
+      // Record result for groups with result sharing (only on true success, not caught errors)
+      if (!task.lastError) {
+        for (const { group, key } of groups) {
+          group.recordResult(key, result);
+        }
+      }
+      return result;
+    } 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, entry.input);
+        if (key !== null) {
+          applicableGroups.push({ group, key });
+        }
+      }
+
+      // No constraints apply anymore (group removed?) → check shouldExecute then run
+      if (applicableGroups.length === 0) {
+        this.checkAllShouldExecute(entry.task, entry.input).then((shouldRun) => {
+          if (!shouldRun) {
+            entry.deferred.resolve(undefined);
+            return;
+          }
+          entry.task.trigger(entry.input).then(
+            (result) => entry.deferred.resolve(result),
+            (err) => entry.deferred.reject(err),
+          );
+        });
+        continue;
+      }
+
+      // Check result sharing — if any applicable group has a shared result, resolve immediately
+      const sharingGroups = applicableGroups.filter(({ group }) => group.hasResultSharing());
+      if (sharingGroups.length > 0) {
+        const groupWithResult = sharingGroups.find(({ group, key }) =>
+          group.getLastResult(key) !== undefined
+        );
+        if (groupWithResult) {
+          entry.deferred.resolve(groupWithResult.group.getLastResult(groupWithResult.key)!.result);
+          continue;
+        }
+      }
+
+      const allCanRun = applicableGroups.every(({ group, key }) => group.canRun(key));
+      if (allCanRun) {
+        // executeWithConstraintTracking handles shouldExecute check internally
+        this.executeWithConstraintTracking(entry.task, entry.input, applicableGroups).then(
+          (result) => entry.deferred.resolve(result),
+          (err) => entry.deferred.reject(err),
+        );
+      } else {
+        stillQueued.push(entry);
+        // Track shortest delay for timer scheduling (cooldown + rate limit)
+        for (const { group, key } of applicableGroups) {
+          const remaining = group.getNextAvailableDelay(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) {
@@ -64,7 +254,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) => {
@@ -75,31 +265,35 @@ export class TaskManager {
            triggerTime,
          );
          if (!announcementResult.shouldTrigger) {
-            console.log('Distributed coordinator result: NOT EXECUTING');
+            logger.log('info', 'Distributed coordinator result: NOT EXECUTING');
            return;
          } else {
-            console.log('Distributed coordinator result: CHOSEN AND EXECUTING');
+            logger.log('info', 'Distributed coordinator result: CHOSEN AND EXECUTING');
          }
        }
-        await task.trigger();
+        try {
+          await this.triggerTaskConstrained(task);
+        } catch (err) {
+          logger.log('error', `TaskManager: scheduled task "${task.name || 'unnamed'}" failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
      },
    );
    task.cronJob = cronJob;
  }

-  private logTaskState(task: Task<any, any>) {
-    console.log(`Taskbuffer schedule triggered task >>${task.name}<<`);
+  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`
      : `unbuffered`;
-    console.log(`Task >>${task.name}<< is ${bufferState}`);
+    logger.log('info', `Task >>${task.name}<< is ${bufferState}`);
  }

  private async performDistributedConsultation(
-    task: Task<any, any>,
+    task: Task<any, any, any>,
    triggerTime: number,
  ): Promise<IDistributedTaskRequestResult> {
-    console.log('Found a distributed coordinator, performing consultation.');
+    logger.log('info', 'Found a distributed coordinator, performing consultation.');

    return this.options.distributedCoordinator.fireDistributedTaskRequest({
      submitterId: this.randomId,
@@ -124,7 +318,7 @@ export class TaskManager {
    }
  }

-  public async descheduleTask(task: Task<any, any>) {
+  public async descheduleTask(task: Task<any, any, any>) {
    await this.descheduleTaskByName(task.name);
  }

@@ -145,6 +339,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
@@ -162,7 +364,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({
@@ -175,7 +377,7 @@ export class TaskManager {
        });
      }
    }
-    
+
    return scheduledTasks;
  }

@@ -189,13 +391,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;
@@ -203,19 +413,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',
@@ -229,15 +438,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
@@ -253,15 +462,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;
    }
  }
--- a/ts/taskbuffer.classes.taskparallel.ts
+++ b/ts/taskbuffer.classes.taskparallel.ts
@@ -13,7 +13,9 @@ export class Taskparallel extends Task {
          this.taskArray.forEach(function (taskArg) {
            promiseArray.push(taskArg.trigger());
          });
-          Promise.all(promiseArray).then(done.resolve);
+          Promise.all(promiseArray)
+            .then((results) => done.resolve(results))
+            .catch((err) => done.reject(err));
          return done.promise;
        },
      },
--- a/ts/taskbuffer.classes.taskrunner.ts
+++ b/ts/taskbuffer.classes.taskrunner.ts
@@ -1,64 +0,0 @@
-import * as plugins from './taskbuffer.plugins.js';
-
-import { Task } from './taskbuffer.classes.task.js';
-
-export class TaskRunner {
-  public maxParrallelJobs: number = 1;
-  public status: 'stopped' | 'running' = 'stopped';
-  public runningTasks: plugins.lik.ObjectMap<Task> =
-    new plugins.lik.ObjectMap<Task>();
-  public qeuedTasks: Task[] = [];
-
-  constructor() {
-    this.runningTasks.eventSubject.subscribe(async (eventArg) => {
-      this.checkExecution();
-    });
-  }
-
-  /**
-   * adds a task to the qeue
-   */
-  public addTask(taskArg: Task) {
-    this.qeuedTasks.push(taskArg);
-    this.checkExecution();
-  }
-
-  /**
-   * set amount of parallel tasks
-   * be careful, you might loose dependability of tasks
-   */
-  public setMaxParallelJobs(maxParrallelJobsArg: number) {
-    this.maxParrallelJobs = maxParrallelJobsArg;
-  }
-
-  /**
-   * starts the task queue
-   */
-  public async start() {
-    this.status = 'running';
-  }
-
-  /**
-   * checks wether execution is on point
-   */
-  public async checkExecution() {
-    if (
-      this.runningTasks.getArray().length < this.maxParrallelJobs &&
-      this.status === 'running' &&
-      this.qeuedTasks.length > 0
-    ) {
-      const nextJob = this.qeuedTasks.shift();
-      this.runningTasks.add(nextJob);
-      await nextJob.trigger();
-      this.runningTasks.remove(nextJob);
-      this.checkExecution();
-    }
-  }
-
-  /**
-   * stops the task queue
-   */
-  public async stop() {
-    this.status = 'stopped';
-  }
-}
--- a/ts/taskbuffer.interfaces.ts
+++ b/ts/taskbuffer.interfaces.ts
@@ -1,4 +1,34 @@
 import type { ITaskStep } from './taskbuffer.classes.taskstep.js';
+import type { Task } from './taskbuffer.classes.task.js';
+
+export interface IRateLimitConfig {
+  maxPerWindow: number;  // max completions allowed within the sliding window
+  windowMs: number;      // sliding window duration in ms
+}
+
+export type TResultSharingMode = 'none' | 'share-latest';
+
+export interface ITaskConstraintGroupOptions<TData extends Record<string, unknown> = Record<string, unknown>> {
+  name: string;
+  constraintKeyForExecution: (task: Task<any, any, TData>, input?: any) => string | null | undefined;
+  maxConcurrent?: number;  // default: Infinity
+  cooldownMs?: number;     // default: 0
+  shouldExecute?: (task: Task<any, any, TData>, input?: any) => boolean | Promise<boolean>;
+  rateLimit?: IRateLimitConfig;
+  resultSharingMode?: TResultSharingMode;  // default: 'none'
+}
+
+export interface ITaskExecution<TData extends Record<string, unknown> = Record<string, unknown>> {
+  task: Task<any, any, TData>;
+  input: any;
+}
+
+export interface IConstrainedTaskEntry {
+  task: Task<any, any, any>;
+  input: any;
+  deferred: import('@push.rocks/smartpromise').Deferred<any>;
+  constraintKeys: Map<string, string>;  // groupName -> key
+}

 export interface ITaskMetadata {
  name: string;
@@ -15,6 +45,9 @@ export interface ITaskMetadata {
  buffered?: boolean;
  bufferMax?: number;
  timeout?: number;
+  lastError?: string;
+  errorCount?: number;
+  labels?: Record<string, string>;
 }

 export interface ITaskExecutionReport {
@@ -36,4 +69,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'
 }
--- a/ts_web/00_commitinfo_data.ts
+++ b/ts_web/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@push.rocks/taskbuffer',
-  version: '3.5.0',
+  version: '6.1.1',
  description: 'A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.'
 }
--- a/ts_web/taskbuffer-dashboard.ts
+++ b/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;
Author	SHA1	Message	Date
Juergen Kunz	b536dc8ba2	v6.1.1	2026-02-15 21:56:39 +00:00
Juergen Kunz	6ca6cf6bc0	fix(tests): improve buffered task tests: add chain, concurrency and queue behavior tests	2026-02-15 21:56:39 +00:00
Juergen Kunz	ed3bd99406	v6.1.0	2026-02-15 21:51:55 +00:00
Juergen Kunz	3ab90d9895	feat(taskbuffer): add sliding-window rate limiting and result-sharing to TaskConstraintGroup and integrate with TaskManager	2026-02-15 21:51:55 +00:00
Juergen Kunz	aee7236e5f	v6.0.1	2026-02-15 21:08:38 +00:00
Juergen Kunz	c89da9e2b0	fix(taskbuffer): no changes to commit	2026-02-15 21:08:38 +00:00
Juergen Kunz	fae13bb944	v6.0.0	2026-02-15 15:15:37 +00:00
Juergen Kunz	0811b04dfd	BREAKING CHANGE(constraints): make TaskConstraintGroup constraint matcher input-aware and add shouldExecute pre-execution hook	2026-02-15 15:15:37 +00:00
Juergen Kunz	33d1c334c4	v5.0.1	2026-02-15 12:36:57 +00:00
Juergen Kunz	b2c0553e30	fix(tests): add and tighten constraint-related tests covering return values, error propagation, concurrency, cooldown timing, and constraint removal	2026-02-15 12:36:57 +00:00
Juergen Kunz	450b62fe5d	v5.0.0	2026-02-15 12:20:01 +00:00
Juergen Kunz	d3e8ff1a11	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.	2026-02-15 12:20:01 +00:00
Juergen Kunz	9d78933a46	v4.2.1	2026-02-15 10:50:30 +00:00
Juergen Kunz	28d9ad1746	fix(deps): bump @push.rocks/smartlog and @types/node; update dependency list version and license link in docs	2026-02-15 10:50:30 +00:00
Juergen Kunz	28312972e0	v4.2.0	2026-01-29 15:13:34 +00:00
Juergen Kunz	a0abcdda90	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	2026-01-29 15:13:34 +00:00
Juergen Kunz	1dd7ca46ff	v4.1.1	2026-01-26 00:54:13 +00:00
Juergen Kunz	6110dd8e71	fix(ts_web): fix web dashboard typings and update generated commit info	2026-01-26 00:54:12 +00:00
Juergen Kunz	3d8fe65b55	v4.1.0	2026-01-26 00:39:30 +00:00
Juergen Kunz	6030fb2805	feat(task): add task labels and push-based task events	2026-01-26 00:39:30 +00:00
Juergen Kunz	9a3a3e3eab	v4.0.0	2026-01-25 23:29:00 +00:00
Juergen Kunz	248383aab1	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.	2026-01-25 23:29:00 +00:00