@basaltkit/scheduler 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Machize Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,267 @@
+# @basaltkit/scheduler
+
+Task scheduler for Basalt applications: define, with a fluent, readable API (`daily().at('03:00')`), tasks that run automatically at set times — backups, reports, cleanups, billing.
+
+You need this module whenever you want something to happen **on a schedule**, rather than in response to a user request.
+
+---
+
+## What this module solves
+
+Many applications need periodic work: deleting expired sessions every night, sending a weekly summary on Sunday, closing billing on the 1st of each month. The traditional way to do this is **cron** — a 5-field format (`minute hour day-of-month month day-of-week`, e.g. `0 3 * * *` = "every day at 03:00") that is powerful but easy to get wrong.
+
+This module lets you declare schedules in readable code — `schedule.call('backup', doBackup).daily().at('03:00')` — without memorizing cron syntax (though it also accepts it as an "escape hatch"). The scheduler wakes up **once a minute**, checks which entries are "due" that minute, and runs them.
+
+It also handles the annoying problems: **timezones** (schedule at 03:00 in Lisbon or São Paulo, not the server's), **overlap** (if the previous run is still in progress, skip the new one with `withoutOverlapping()`), **failures** (`onFailure` handler per entry; without it, the error is aggregated without crashing the process) and **testability** (the `tick(data)` method is deterministic — in tests you call it with a fixed date, with no need to wait on real clocks).
+
+## Installation
+
+```bash
+pnpm add @basaltkit/scheduler
+```
+
+Depends on `@basaltkit/core` and integrates (optionally) with `@basaltkit/queue`.
+
+## Getting started in 5 minutes
+
+**1. Register the plugin and define the schedules** (e.g. `src/app.ts`):
+
+```ts
+import { createApp } from '@basaltkit/core'
+import { schedulerPlugin } from '@basaltkit/scheduler'
+
+const app = await createApp({
+  plugins: [
+    schedulerPlugin({
+      define: (schedule) => {
+        // every minute
+        schedule.call('heartbeat', () => console.log('still alive'))
+
+        // every day at 03:00 UTC
+        schedule
+          .call('backup', async () => {
+            // do the backup…
+          })
+          .daily()
+          .at('03:00')
+      },
+    }),
+  ],
+}).boot()
+```
+
+**2. There's no step 2.** On `boot`, the plugin calls your `define`, and the internal timer starts on its own (it aligns to the next minute and then checks every 60 seconds). On application `shutdown`, the timer stops.
+
+To see what's scheduled:
+
+```ts
+import { SCHEDULER } from '@basaltkit/scheduler'
+
+console.log(app.container.get(SCHEDULER).list())
+// [{ name: 'heartbeat', cron: '* * * * *', timezone: 'UTC' },
+//  { name: 'backup',    cron: '0 3 * * *', timezone: 'UTC' }]
+```
+
+## Usage guide
+
+### Fluent frequencies
+
+Each method returns the entry itself, so they can be chained:
+
+```ts
+import { Scheduler } from '@basaltkit/scheduler'
+
+const schedule = new Scheduler()
+
+schedule.call('a', task).everyMinute()          // * * * * *
+schedule.call('b', task).everyMinutes(15)       // */15 * * * *
+schedule.call('c', task).hourly()               // 0 * * * *   (at minute 0)
+schedule.call('d', task).daily()                // 0 0 * * *   (midnight)
+schedule.call('e', task).daily().at('03:30')    // 30 3 * * *
+schedule.call('f', task).weekly()               // 0 0 * * 0   (Sunday at midnight)
+schedule.call('g', task).weekly().sundays().at('08:00') // 0 8 * * 0
+schedule.call('h', task).monthly().at('00:30')  // 30 0 1 * *  (the 1st of the month)
+schedule.call('i', task).mondays().at('09:00')  // days of the week: sundays()…saturdays()
+```
+
+`at('HH:mm')` combines with `daily()`/`weekly()`/`monthly()` — it sets the hour and minute.
+
+### Direct cron expression
+
+When the fluent API isn't enough, pass raw cron (5 fields; supports `*`, `*/n` steps, `a-b` ranges and `a,b,c` lists):
+
+```ts
+// every 15 minutes, from 9am to 5pm, Monday to Friday
+schedule.call('sync', sync).cron('*/15 9-17 * * 1-5')
+```
+
+An invalid expression throws `CronParseError` (code `CRON_INVALID`).
+
+### Timezones
+
+By default, times are interpreted in **UTC**. Use `timezone()` with an IANA name:
+
+```ts
+schedule
+  .call('report', generateReport)
+  .daily()
+  .at('03:00')
+  .timezone('America/Sao_Paulo') // 03:00 in São Paulo = 06:00 UTC
+```
+
+### Avoiding overlap: `withoutOverlapping()`
+
+If a task takes longer than the interval between runs, the new run is **skipped** while the previous one is in progress:
+
+```ts
+const entry = schedule
+  .call('slow-import', importEverything)
+  .everyMinute()
+  .withoutOverlapping()
+
+// entry.skippedOverlaps counts the skipped runs (observability/tests)
+```
+
+### Handling failures: `onFailure()`
+
+```ts
+schedule
+  .call('fragile', taskThatMightFail)
+  .hourly()
+  .onFailure((error) => {
+    console.error('task failed', error)
+  })
+```
+
+- **With** `onFailure`: the error is delivered to the handler and doesn't propagate.
+- **Without** `onFailure`: on manual `tick()`, errors from due entries are aggregated into an `AggregateError` (all due entries run in the same call). In automatic mode (timer), the failure is swallowed so as not to crash the process — so in production, always set `onFailure` (or use `schedule.job(...)`, see below, and leave retries to the queue).
+
+### Scheduling queue jobs: `schedule.job()`
+
+Instead of running the task in the scheduler's own process, you can schedule the **dispatch** of an `@basaltkit/queue` job — the heavy lifting runs on the worker, with retries and context:
+
+```ts
+import { createApp } from '@basaltkit/core'
+import { defineJob, queuePlugin } from '@basaltkit/queue'
+import { schedulerPlugin } from '@basaltkit/scheduler'
+import { z } from 'zod'
+
+const ReconcileBilling = defineJob({
+  name: 'billing.reconcile',
+  schema: z.object({ mode: z.string() }),
+  async handle({ mode }) { /* reconcile… */ },
+})
+
+const app = await createApp({
+  plugins: [
+    queuePlugin({ jobs: [ReconcileBilling] }),
+    schedulerPlugin({
+      define: (schedule) => {
+        schedule.job(ReconcileBilling, { mode: 'full' }).daily().at('03:00')
+      },
+    }),
+  ],
+}).boot()
+```
+
+The entry is named after the job (`billing.reconcile`). If the job takes no payload (`T = void`), just call `schedule.job(MyJob)`.
+
+### Testing deterministically
+
+`tick(date)` runs everything due at that exact instant — no real timers involved:
+
+```ts
+import { Scheduler } from '@basaltkit/scheduler'
+
+const scheduler = new Scheduler()
+let runs = 0
+scheduler.call('backup', () => void runs++).daily().at('03:00')
+
+await scheduler.tick(new Date('2026-08-05T10:15:00Z')) // not 03:00 → doesn't run
+await scheduler.tick(new Date('2026-08-05T03:00:00Z')) // runs
+console.log(runs) // 1
+```
+
+In tests with the plugin, pass `autostart: false` so the timer doesn't start.
+
+## API reference
+
+### `schedulerPlugin(options?: SchedulerPluginOptions)`
+
+Registers a `Scheduler` (singleton) under the `SCHEDULER` token; on `boot` it calls `define`, publishes the entries to the container's metadata (key `schedule:entries`, consumed by the `basalt schedule:list` CLI) and starts the timer; on `shutdown` it calls `stop()`.
+
+| Option | Type | Required? | Default | Description |
+|---|---|---|---|---|
+| `define` | `(schedule: Scheduler) => void` | No | — | Callback where you declare the schedules (receives the Scheduler at boot). |
+| `autostart` | `boolean` | No | `true` | Starts the timer at boot. Turn off in tests. |
+
+### `class Scheduler`
+
+| Method | Signature | Description |
+|---|---|---|
+| `call` | `(name: string, task: () => void \| Promise<void>) => ScheduleEntry` | Schedules a function with a name. |
+| `job` | `<T>(job: JobDefinition<T>, payload?) => ScheduleEntry` | Schedules the `dispatch` of an `@basaltkit/queue` job (payload required if the job needs one). |
+| `list` | `() => { name, cron, timezone }[]` | Describes all entries. |
+| `tick` | `(date?: Date) => Promise<void>` | Runs the entries due at that instant (default: now). Aggregates failures without `onFailure` into an `AggregateError`. |
+| `start` | `() => void` | Aligns to the next minute and then `tick()`s every 60s. Idempotent. |
+| `stop` | `() => void` | Stops the timers. |
+
+### `class ScheduleEntry` (returned by `call`/`job`)
+
+Frequency methods (all return `this`): `everyMinute()`, `everyMinutes(n)`, `hourly()`, `daily()`, `weekly()`, `monthly()`, `at('HH:mm')`, `cron(expression)`, `sundays()`, `mondays()`, `tuesdays()`, `wednesdays()`, `thursdays()`, `fridays()`, `saturdays()`.
+
+| Method/property | Type | Default | Description |
+|---|---|---|---|
+| `timezone(tz)` | `(tz: string) => this` | `'UTC'` | IANA timezone in which the time is interpreted. |
+| `withoutOverlapping()` | `() => this` | off | Skips the run if the previous one is still in progress. |
+| `onFailure(handler)` | `((error: unknown) => void) => this` | — | Receives the error instead of propagating it. |
+| `describe()` | `() => { name, cron, timezone }` | — | Description of the entry. |
+| `isDue(date)` | `(date: Date) => boolean` | — | Is the entry due at this instant? |
+| `skippedOverlaps` | `number` | `0` | Counter of runs skipped due to overlap. |
+| `run()` | `() => Promise<void>` | — | **Advanced/internal**: runs with overlap guard and failure handling. |
+
+Without any frequency method, the entry runs **every minute** (initial cron fields are `* * * * *`).
+
+### Cron utilities (Advanced)
+
+Exported for tooling and tests; you don't usually need them:
+
+| Export | Signature | Description |
+|---|---|---|
+| `parseCron` | `(expression: string) => CronFields` | Splits a 5-field expression; throws `CronParseError` if invalid. |
+| `cronMatches` | `(fields: CronFields, date: Date, timeZone?: string) => boolean` | Does the instant match the expression (in the given timezone)? |
+| `fieldMatches` | `(field: string, value: number) => boolean` | Does a field (`*`, `*/n`, `a-b`, `a,b,c`, value) accept the number? |
+| `zonedParts` | `(date: Date, timeZone = 'UTC') => ZonedParts` | Breaks the instant down into minute/hour/day/month/day-of-week in the timezone. |
+| `CronParseError` | class (`BasaltError`, code `CRON_INVALID`) | Invalid cron expression. |
+| `CronFields`, `ZonedParts` | types | Cron fields as strings; numeric parts of the instant. |
+
+### Token
+
+- `SCHEDULER: Token<Scheduler>` — to get the Scheduler from the container: `app.container.get(SCHEDULER)`.
+
+## Common errors and solutions (FAQ)
+
+**My `daily().at('03:00')` task runs at the wrong time.**
+Times are UTC by default. Add `.timezone('Europe/Lisbon')` (or your IANA timezone).
+
+**`CronParseError: expected 5 fields`.**
+`cron()` only accepts the classic 5-field format (`min hour day month day-of-week`). 6-field formats (with seconds) are not supported.
+
+**The task runs twice (two servers).**
+The scheduler runs in every process where the plugin starts. If you have multiple replicas, enable the scheduler on only one (e.g. via an environment variable) or schedule `schedule.job(...)` with idempotent jobs.
+
+**A task failed and I didn't see anything.**
+In automatic mode, failures without `onFailure` are silenced so as not to crash the process. Set `onFailure` on each entry (or log inside it).
+
+**I need second-level precision.**
+Not possible — the resolution is the minute (the `tick` runs every 60s), just like classic cron.
+
+**In tests, the process doesn't exit.**
+Pass `autostart: false` to the plugin, or call `scheduler.stop()`. (The timers use `unref()`, so they usually don't hold the process open, but in tests it's best not to start them.)
+
+## How it connects to other modules
+
+- **`@basaltkit/core`** — `schedulerPlugin` is a core plugin (register/boot/shutdown); entries are published to the container's metadata registry (`ensureMetadata` → key `schedule:entries`) for the `basalt schedule:list` CLI; `CronParseError` extends `BasaltError`.
+- **`@basaltkit/queue`** — `schedule.job(MyJob, payload)` schedules a job's *dispatch*: the scheduler only enqueues it; execution, retries and context are handled by the queue and its workers. This is the recommended pattern for heavy or critical tasks.
+- **`@basaltkit/logger`** — use the logger inside tasks/`onFailure` to get structured traces of the runs.
+- **`@basaltkit/audit` / `@basaltkit/activity`** — scheduled tasks can record audit or activity entries (e.g. `audit.record('maintenance.run')`) to leave a trail of the automated work.

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+import * as _basaltkit_core from '@basaltkit/core';
+import { BasaltError } from '@basaltkit/core';
+import { JobDefinition } from '@basaltkit/queue';
+
+declare class CronParseError extends BasaltError {
+    constructor(expression: string, detail: string);
+}
+interface CronFields {
+    minute: string;
+    hour: string;
+    dayOfMonth: string;
+    month: string;
+    dayOfWeek: string;
+}
+declare function parseCron(expression: string): CronFields;
+/** Supports: asterisk, steps (asterisk/n), single value, a-b ranges and a,b,c lists. */
+declare function fieldMatches(field: string, value: number): boolean;
+interface ZonedParts {
+    minute: number;
+    hour: number;
+    dayOfMonth: number;
+    month: number;
+    dayOfWeek: number;
+}
+/** Decomposes an instant into the cron fields, in the requested time zone (default UTC). */
+declare function zonedParts(date: Date, timeZone?: string): ZonedParts;
+declare function cronMatches(fields: CronFields, date: Date, timeZone?: string): boolean;
+
+type Task = () => void | Promise<void>;
+/**
+ * A scheduled entry, built fluently:
+ *
+ * schedule.job(ReconcileBilling).daily().at('03:00').timezone('UTC')
+ * schedule.call('purge-cache', () => cache.flush()).everyMinute().withoutOverlapping()
+ */
+declare class ScheduleEntry {
+    readonly name: string;
+    private readonly task;
+    private fields;
+    private tz;
+    private noOverlap;
+    private failureHandler;
+    private running;
+    /** count of executions skipped due to overlap — visible for observability/tests */
+    skippedOverlaps: number;
+    constructor(name: string, task: Task);
+    everyMinute(): this;
+    everyMinutes(n: number): this;
+    hourly(): this;
+    daily(): this;
+    weekly(): this;
+    monthly(): this;
+    /** 'HH:mm' time — combines with daily/weekly/monthly. */
+    at(time: string): this;
+    /** Raw cron expression (5 fields) — escape hatch. */
+    cron(expression: string): this;
+    sundays(): this;
+    mondays(): this;
+    tuesdays(): this;
+    wednesdays(): this;
+    thursdays(): this;
+    fridays(): this;
+    saturdays(): this;
+    timezone(tz: string): this;
+    /** If the previous execution is still running, the new one is skipped. */
+    withoutOverlapping(): this;
+    onFailure(handler: (error: unknown) => void): this;
+    /** Entry description — consumed by `basalt schedule list`. */
+    describe(): {
+        name: string;
+        cron: string;
+        timezone: string;
+    };
+    isDue(date: Date): boolean;
+    /** @internal runs the task with the overlap guard and failure handling. */
+    run(): Promise<void>;
+    private onDayOfWeek;
+}
+declare class Scheduler {
+    private readonly entries;
+    private timer;
+    private interval;
+    /** Schedules the dispatch of a @basaltkit/queue job. */
+    job<T>(job: JobDefinition<T>, ...payload: T extends void ? [] : [T]): ScheduleEntry;
+    /** Schedules a named function. */
+    call(name: string, task: Task): ScheduleEntry;
+    list(): {
+        name: string;
+        cron: string;
+        timezone: string;
+    }[];
+    /**
+     * Runs the entries due at the given instant. Deterministic — this is what
+     * the tests call directly and what the timer calls every minute.
+     * Failures (without onFailure) are aggregated; all due entries run.
+     */
+    tick(date?: Date): Promise<void>;
+    /** Aligns to the next minute and then runs tick() every 60s. */
+    start(): void;
+    stop(): void;
+    private safeTick;
+    private add;
+}
+declare const SCHEDULER: _basaltkit_core.Token<Scheduler>;
+interface SchedulerPluginOptions {
+    /** Callback that defines the schedules — receives the Scheduler at boot. */
+    define?: (schedule: Scheduler) => void;
+    /** Starts the timer at boot. Default: true (turn off in tests). */
+    autostart?: boolean;
+}
+declare function schedulerPlugin(options?: SchedulerPluginOptions): _basaltkit_core.BasaltPlugin<unknown>;
+
+export { type CronFields, CronParseError, SCHEDULER, ScheduleEntry, Scheduler, type SchedulerPluginOptions, type ZonedParts, cronMatches, fieldMatches, parseCron, schedulerPlugin, zonedParts };

package/dist/index.js

@@ -0,0 +1,286 @@
+// src/index.ts
+import { createToken, definePlugin, ensureMetadata } from "@basaltkit/core";
+
+// src/cron.ts
+import { BasaltError } from "@basaltkit/core";
+var CronParseError = class extends BasaltError {
+  constructor(expression, detail) {
+    super("CRON_INVALID", `Invalid cron expression "${expression}": ${detail}`);
+  }
+};
+function parseCron(expression) {
+  const parts = expression.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new CronParseError(expression, `expected 5 fields, received ${parts.length}`);
+  }
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+  return { minute, hour, dayOfMonth, month, dayOfWeek };
+}
+function cronToString(fields) {
+  return [fields.minute, fields.hour, fields.dayOfMonth, fields.month, fields.dayOfWeek].join(" ");
+}
+function fieldMatches(field, value) {
+  if (field === "*") return true;
+  return field.split(",").some((part) => {
+    const step = /^\*\/(\d+)$/.exec(part);
+    if (step) return value % Number(step[1]) === 0;
+    const range = /^(\d+)-(\d+)$/.exec(part);
+    if (range) return value >= Number(range[1]) && value <= Number(range[2]);
+    return Number(part) === value;
+  });
+}
+var WEEKDAYS = {
+  Sun: 0,
+  Mon: 1,
+  Tue: 2,
+  Wed: 3,
+  Thu: 4,
+  Fri: 5,
+  Sat: 6
+};
+function zonedParts(date, timeZone = "UTC") {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    minute: "numeric",
+    hour: "numeric",
+    day: "numeric",
+    month: "numeric",
+    weekday: "short",
+    hour12: false
+  });
+  const parts = {};
+  for (const part of formatter.formatToParts(date)) {
+    parts[part.type] = part.value;
+  }
+  return {
+    minute: Number(parts["minute"]),
+    // Intl with hour12:false may emit 24 for midnight
+    hour: Number(parts["hour"]) % 24,
+    dayOfMonth: Number(parts["day"]),
+    month: Number(parts["month"]),
+    dayOfWeek: WEEKDAYS[parts["weekday"]]
+  };
+}
+function cronMatches(fields, date, timeZone) {
+  const parts = zonedParts(date, timeZone);
+  return fieldMatches(fields.minute, parts.minute) && fieldMatches(fields.hour, parts.hour) && fieldMatches(fields.dayOfMonth, parts.dayOfMonth) && fieldMatches(fields.month, parts.month) && fieldMatches(fields.dayOfWeek, parts.dayOfWeek);
+}
+
+// src/index.ts
+var ScheduleEntry = class {
+  constructor(name, task) {
+    this.name = name;
+    this.task = task;
+  }
+  name;
+  task;
+  fields = {
+    minute: "*",
+    hour: "*",
+    dayOfMonth: "*",
+    month: "*",
+    dayOfWeek: "*"
+  };
+  tz = "UTC";
+  noOverlap = false;
+  failureHandler;
+  running = false;
+  /** count of executions skipped due to overlap — visible for observability/tests */
+  skippedOverlaps = 0;
+  everyMinute() {
+    this.fields = { minute: "*", hour: "*", dayOfMonth: "*", month: "*", dayOfWeek: "*" };
+    return this;
+  }
+  everyMinutes(n) {
+    this.everyMinute();
+    this.fields.minute = `*/${n}`;
+    return this;
+  }
+  hourly() {
+    this.everyMinute();
+    this.fields.minute = "0";
+    return this;
+  }
+  daily() {
+    this.hourly();
+    this.fields.hour = "0";
+    return this;
+  }
+  weekly() {
+    this.daily();
+    this.fields.dayOfWeek = "0";
+    return this;
+  }
+  monthly() {
+    this.daily();
+    this.fields.dayOfMonth = "1";
+    return this;
+  }
+  /** 'HH:mm' time — combines with daily/weekly/monthly. */
+  at(time) {
+    const [hour, minute] = time.split(":");
+    this.fields.hour = String(Number(hour));
+    this.fields.minute = String(Number(minute ?? 0));
+    return this;
+  }
+  /** Raw cron expression (5 fields) — escape hatch. */
+  cron(expression) {
+    this.fields = parseCron(expression);
+    return this;
+  }
+  sundays() {
+    return this.onDayOfWeek(0);
+  }
+  mondays() {
+    return this.onDayOfWeek(1);
+  }
+  tuesdays() {
+    return this.onDayOfWeek(2);
+  }
+  wednesdays() {
+    return this.onDayOfWeek(3);
+  }
+  thursdays() {
+    return this.onDayOfWeek(4);
+  }
+  fridays() {
+    return this.onDayOfWeek(5);
+  }
+  saturdays() {
+    return this.onDayOfWeek(6);
+  }
+  timezone(tz) {
+    this.tz = tz;
+    return this;
+  }
+  /** If the previous execution is still running, the new one is skipped. */
+  withoutOverlapping() {
+    this.noOverlap = true;
+    return this;
+  }
+  onFailure(handler) {
+    this.failureHandler = handler;
+    return this;
+  }
+  /** Entry description — consumed by `basalt schedule list`. */
+  describe() {
+    return { name: this.name, cron: cronToString(this.fields), timezone: this.tz };
+  }
+  isDue(date) {
+    return cronMatches(this.fields, date, this.tz);
+  }
+  /** @internal runs the task with the overlap guard and failure handling. */
+  async run() {
+    if (this.noOverlap && this.running) {
+      this.skippedOverlaps++;
+      return;
+    }
+    this.running = true;
+    try {
+      await this.task();
+    } catch (error) {
+      if (!this.failureHandler) throw error;
+      this.failureHandler(error);
+    } finally {
+      this.running = false;
+    }
+  }
+  onDayOfWeek(day) {
+    this.fields.dayOfWeek = String(day);
+    return this;
+  }
+};
+var Scheduler = class {
+  entries = [];
+  timer;
+  interval;
+  /** Schedules the dispatch of a @basaltkit/queue job. */
+  job(job, ...payload) {
+    return this.add(new ScheduleEntry(job.name, () => job.dispatch(payload[0])));
+  }
+  /** Schedules a named function. */
+  call(name, task) {
+    return this.add(new ScheduleEntry(name, task));
+  }
+  list() {
+    return this.entries.map((entry) => entry.describe());
+  }
+  /**
+   * Runs the entries due at the given instant. Deterministic — this is what
+   * the tests call directly and what the timer calls every minute.
+   * Failures (without onFailure) are aggregated; all due entries run.
+   */
+  async tick(date = /* @__PURE__ */ new Date()) {
+    const due = this.entries.filter((entry) => entry.isDue(date));
+    const errors = [];
+    await Promise.all(
+      due.map(async (entry) => {
+        try {
+          await entry.run();
+        } catch (error) {
+          errors.push(error);
+        }
+      })
+    );
+    if (errors.length > 0) {
+      throw new AggregateError(errors, `Failure in ${errors.length} scheduled task(s)`);
+    }
+  }
+  /** Aligns to the next minute and then runs tick() every 60s. */
+  start() {
+    if (this.timer || this.interval) return;
+    const msToNextMinute = 6e4 - Date.now() % 6e4;
+    this.timer = setTimeout(() => {
+      void this.safeTick();
+      this.interval = setInterval(() => void this.safeTick(), 6e4);
+      this.interval.unref?.();
+    }, msToNextMinute);
+    this.timer.unref?.();
+  }
+  stop() {
+    if (this.timer) clearTimeout(this.timer);
+    if (this.interval) clearInterval(this.interval);
+    this.timer = void 0;
+    this.interval = void 0;
+  }
+  async safeTick() {
+    try {
+      await this.tick();
+    } catch {
+    }
+  }
+  add(entry) {
+    this.entries.push(entry);
+    return entry;
+  }
+};
+var SCHEDULER = createToken("scheduler");
+function schedulerPlugin(options = {}) {
+  return definePlugin({
+    name: "basalt:scheduler",
+    register({ container }) {
+      container.singleton(SCHEDULER, () => new Scheduler());
+    },
+    boot({ container }) {
+      const scheduler = container.get(SCHEDULER);
+      options.define?.(scheduler);
+      const metadata = ensureMetadata(container);
+      for (const entry of scheduler.list()) metadata.add("schedule:entries", entry);
+      if (options.autostart !== false) scheduler.start();
+    },
+    shutdown({ container }) {
+      container.get(SCHEDULER).stop();
+    }
+  });
+}
+export {
+  CronParseError,
+  SCHEDULER,
+  ScheduleEntry,
+  Scheduler,
+  cronMatches,
+  fieldMatches,
+  parseCron,
+  schedulerPlugin,
+  zonedParts
+};

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@basaltkit/scheduler",
+  "version": "1.0.0",
+  "description": "Fluent Basalt scheduler: schedule.job(X).daily().at('03:00'), timezones, withoutOverlapping and @basaltkit/queue integration.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@basaltkit/core": "^1.0.0",
+    "@basaltkit/queue": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.1.0",
+    "zod": "^3.24.0",
+    "@basaltkit/tsconfig": "^0.24.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Zebedeu/basalt.git",
+    "directory": "packages/scheduler"
+  },
+  "homepage": "https://github.com/Zebedeu/basalt/tree/main/packages/scheduler#readme",
+  "bugs": "https://github.com/Zebedeu/basalt/issues",
+  "keywords": [
+    "basalt",
+    "typescript",
+    "scheduler",
+    "cron"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}