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)

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

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

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

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

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

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 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[]

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

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

Decorators require the accessor keyword:

@property({ type: String })
accessor myProp = 'default';

@state()
accessor count = 0;