@xlsft/worker

@xlsft/worker is a lightweight zero-boilerplate task framework designed to run cron-based, date-based, and event-driven background jobs in Node.js, Deno, and Bun environments. Built with TypeScript, it focuses on strong typing, simplicity, and automatic task discovery without requiring manual registration or complex configuration. Once initialized, the worker scans the tasks directory and dynamically loads every file matching the .task suffix, automatically registering triggers and schedules.

The architecture revolves around defineWorker, which bootstraps the runtime and loads tasks from a specified directory, and defineTask, which defines the task logic together with its trigger. Three trigger types are supported: cron scheduling (either classic cron syntax or a fully typed schedule schema), one-time execution at a specific date, and event-based execution through an internal EventEmitter. If no explicit trigger is provided, the task filename automatically becomes its event name, allowing it to be triggered programmatically without extra configuration.

Each execution receives a TaskEvent instance — an immutable instance, containing execution metadata, current state, trigger information, and an emit method for invoking other tasks. This enables internal orchestration and chaining without external dependencies. Tasks can trigger other tasks, forming event-driven pipelines, and can control their lifecycle using cancel and kill.

Execution behavior can be fine-tuned using built-in options: retry defines how many additional attempts should be made after failure, times specifies how many times a task should run per trigger, and delay sets the interval between executions or retries. This eliminates the need for custom retry loops or manual timers. The project is already tested in production environments, with its API and internal structure considered stable, while ongoing improvements focus on edge-case handling, logging enhancements, and coroutine support.

@xlsft/worker is positioned as a clean and efficient alternative to heavy job queues and complex schedulers, providing a strongly typed, minimalistic, and predictable background task framework ready to use out of the box.