taskbuffer/readme.hints.md

# Taskbuffer Hints

## Error Handling (v3.6.0+)
- `Task` now has `catchErrors` constructor option (default: `false`)
- Default behavior: `trigger()` rejects when taskFunction throws (breaking change from pre-3.6)
- Set `catchErrors: true` to swallow errors (old behavior) - returns `undefined` on error
- Error state tracked via `lastError?: Error`, `errorCount: number`, `clearError()`
- `getMetadata()` status uses all four values: `'idle'` | `'running'` | `'completed'` | `'failed'`
- All peripheral classes (Taskchain, Taskparallel, TaskRunner, BufferRunner, TaskDebounced, TaskManager) have proper error propagation/handling
- `console.log` calls replaced with `logger.log()` throughout

## Breaking API Rename (TaskRunner)
- `maxParrallelJobs` → `maxParallelJobs`
- `qeuedTasks` → `queuedTasks`
- JSDoc typos fixed: "qeue" → "queue", "wether" → "whether", "loose" → "lose"
- The `setMaxParallelJobs()` parameter also renamed from `maxParrallelJobsArg` to `maxParallelJobsArg`

## Error Context Improvements
- **TaskChain**: Errors now wrap the original with context: chain name, failing task name, and task index. Original error preserved via `.cause`
- **BufferRunner**: When `catchErrors: false`, buffered task errors now reject the trigger promise (via `CycleCounter.informOfCycleError`) instead of silently resolving with `undefined`
- **TaskChain stubs completed**: `removeTask(task)` returns `boolean`, `shiftTask()` returns `Task | undefined`

## Task Labels (v4.1.0+)
- `Task` constructor accepts optional `labels?: Record<string, string>`
- Helper methods: `setLabel(key, value)`, `getLabel(key)`, `removeLabel(key)`, `hasLabel(key, value?)`
- `getMetadata()` includes `labels` (shallow copy)
- `TaskManager.getTasksByLabel(key, value)` returns matching `Task[]`
- `TaskManager.getTasksMetadataByLabel(key, value)` returns matching `ITaskMetadata[]`

## Push-Based Events (v4.1.0+)
- `Task.eventSubject`: rxjs `Subject<ITaskEvent>` emitting `'started'`, `'step'`, `'completed'`, `'failed'` events
- `TaskManager.taskSubject`: aggregated `Subject<ITaskEvent>` from all added tasks
- `TaskManager.removeTask(task)` unsubscribes and removes from map
- `TaskManager.stop()` cleans up all event subscriptions
- Exported types: `ITaskEvent`, `TTaskEventType`

## Project Structure
- Source in `ts/`, web components in `ts_web/`
- Tests in `test/` - naming: `*.node.ts`, `*.browser.ts`, `*.both.ts`
- 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`