@arkstack/scheduler 0.17.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Toneflix Technologies Limited
+
+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,138 @@
+# @arkstack/scheduler
+
+[![@arkstack/scheduler](https://img.shields.io/npm/dt/@arkstack/scheduler?style=flat-square&label=@arkstack/scheduler&link=https%3A%2F%2Fwww.npmjs.com%2Fpackage%2F@arkstack/scheduler)](https://www.npmjs.com/package/@arkstack/scheduler)
+
+Task scheduling for [Arkstack](https://arkstack.toneflix.net). Define scheduled tasks fluently in code instead of managing a crowd of cron entries — a single system cron entry drives everything.
+
+## Install
+
+```sh
+pnpm add @arkstack/scheduler
+ark publish --package @arkstack/scheduler   # writes src/routes/console.ts
+```
+
+Full app templates include it and a `src/routes/console.ts` already.
+
+## Define your schedule
+
+In `src/routes/console.ts`:
+
+```ts
+import { Schedule } from '@arkstack/scheduler';
+
+Schedule.command('cache:prune').hourly();
+
+Schedule.call(async () => {
+  await pruneTempFiles();
+})
+  .dailyAt('01:30')
+  .withoutOverlapping();
+
+Schedule.job(new SendDigest()).weeklyOn(1, '08:00');
+
+Schedule.exec('backup.sh').daily().onOneServer();
+```
+
+| Task type                       | Runs                                           |
+| ------------------------------- | ---------------------------------------------- |
+| `Schedule.command(name, args?)` | An Arkstack CLI command (`ark <name>`)         |
+| `Schedule.call(fn)`             | A callback                                     |
+| `Schedule.job(job)`             | A queued job (dispatched via `@arkstack/jobs`) |
+| `Schedule.exec(cmd, args?)`     | A shell command                                |
+
+## Run it
+
+The scheduler evaluates due tasks once a minute. In production, add **one** cron entry:
+
+```
+* * * * * cd /path/to/app && npx ark schedule:run >> /dev/null 2>&1
+```
+
+During development, run the foreground worker instead:
+
+```sh
+ark schedule:work    # evaluates the schedule every minute until stopped
+ark schedule:list    # list tasks with their next run time
+```
+
+## Frequencies
+
+```ts
+Schedule.command('x').everyMinute();
+Schedule.command('x').everyFiveMinutes(); // */5 * * * *
+Schedule.command('x').everyThirtyMinutes();
+Schedule.command('x').hourly();
+Schedule.command('x').hourlyAt(15);
+Schedule.command('x').daily();
+Schedule.command('x').dailyAt('13:00');
+Schedule.command('x').twiceDaily(1, 13);
+Schedule.command('x').weekly();
+Schedule.command('x').weeklyOn(1, '8:00'); // Monday 08:00
+Schedule.command('x').monthly();
+Schedule.command('x').monthlyOn(15, '17:00');
+Schedule.command('x').quarterly();
+Schedule.command('x').yearly();
+Schedule.command('x').cron('*/10 9-17 * * 1-5'); // raw cron
+```
+
+Day-of-week constraints, with time layered on top:
+
+```ts
+Schedule.command('x').weekdays().at('9:00');
+Schedule.command('x').weekends().hourly();
+Schedule.command('x').mondays();
+Schedule.command('x').days([1, 4]); // Monday & Thursday
+```
+
+Set the timezone the expression is evaluated in:
+
+```ts
+Schedule.command('x').dailyAt('09:00').timezone('America/New_York');
+```
+
+## Constraints
+
+```ts
+Schedule.command('x')
+  .daily()
+  .when(async () => await featureEnabled('reports')) // run only when truthy
+  .skip(() => isHoliday()) // skip when truthy
+  .environments('production', 'staging') // limit by APP_ENV
+  .between('09:00', '17:00'); // only within a daily window
+```
+
+`unlessBetween('22:00', '06:00')` runs _outside_ a window (overnight ranges handled).
+
+## Overlaps, single-server & background
+
+```ts
+Schedule.command('report:build').everyFiveMinutes().withoutOverlapping();
+Schedule.exec('backup.sh').daily().onOneServer();
+Schedule.exec('long-import.sh').daily().runInBackground();
+```
+
+`withoutOverlapping()` and `onOneServer()` coordinate through `@arkstack/cache`, so they work across processes and servers. Configure a shared cache store (`redis` or `database`) for `onOneServer()` to be effective; without a cache the scheduler falls back to a process-local lock.
+
+## Hooks
+
+```ts
+Schedule.command('report:build')
+  .daily()
+  .before(() => logger.info('building report'))
+  .onSuccess(() => notifyOk())
+  .onFailure((error) => notifyFailed(error))
+  .after(() => logger.info('done'));
+```
+
+## API
+
+- `Schedule.command / call / job / exec` — register a task, returns a `ScheduledEvent` for chaining.
+- `Schedule.events()` / `Schedule.dueEvents(date?)` — inspect registered / due events.
+- `ScheduledEvent` — the fluent builder (frequencies, day constraints, `timezone`, `when`, `skip`, `environments`, `between`, `unlessBetween`, `withoutOverlapping`, `onOneServer`, `runInBackground`, `before`/`after`/`onSuccess`/`onFailure`, `description`, `name`).
+- Commands: `schedule:run`, `schedule:work`, `schedule:list`.
+
+Cron evaluation is powered by [croner](https://github.com/hexagon/croner). See the [scheduling guide](https://arkstack.toneflix.net/guide/scheduling) for the full walkthrough.
+
+## License
+
+MIT

package/dist/commands/ScheduleListCommand.d.ts

@@ -0,0 +1,14 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/commands/ScheduleListCommand.d.ts
+/**
+ * List the application's scheduled tasks with their cron expression and next
+ * run time.
+ */
+declare class ScheduleListCommand extends Command {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<void>;
+}
+//#endregion
+export { ScheduleListCommand };

package/dist/commands/ScheduleListCommand.js

@@ -0,0 +1,28 @@
+import { n as Schedule, t as loadSchedule } from "../loader-zz_XJXwZ.js";
+import { Command } from "@h3ravel/musket";
+//#region src/commands/ScheduleListCommand.ts
+/**
+* List the application's scheduled tasks with their cron expression and next
+* run time.
+*/
+var ScheduleListCommand = class extends Command {
+	signature = "schedule:list";
+	description = "List the scheduled tasks.";
+	async handle() {
+		const loaded = await loadSchedule();
+		const events = Schedule.events();
+		if (!events.length) {
+			this.warn(loaded ? "No scheduled tasks are defined in src/routes/console.ts." : "No src/routes/console.ts found.");
+			return;
+		}
+		const now = /* @__PURE__ */ new Date();
+		for (const event of events) {
+			const next = event.nextRunAt(now);
+			const when = next ? `next: ${next.toISOString()}` : "next: —";
+			this.line(`  ${event.expression.padEnd(16)}  ${event.descriptionValue.padEnd(28)}  ${when}`);
+		}
+		this.info(`${events.length} scheduled task(s).`);
+	}
+};
+//#endregion
+export { ScheduleListCommand };

package/dist/commands/ScheduleRunCommand.d.ts

@@ -0,0 +1,18 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/commands/ScheduleRunCommand.d.ts
+/**
+ * Run the scheduled tasks that are due right now. Invoke this once a minute from
+ * cron:
+ *
+ * ```
+ * * * * * * cd /path/to/app && npx ark schedule:run >> /dev/null 2>&1
+ * ```
+ */
+declare class ScheduleRunCommand extends Command {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<void>;
+}
+//#endregion
+export { ScheduleRunCommand };

package/dist/commands/ScheduleRunCommand.js

@@ -0,0 +1,33 @@
+import { t as loadSchedule } from "../loader-zz_XJXwZ.js";
+import { t as runDueEvents } from "../runner-DFEYebtg.js";
+import { Command } from "@h3ravel/musket";
+//#region src/commands/ScheduleRunCommand.ts
+/**
+* Run the scheduled tasks that are due right now. Invoke this once a minute from
+* cron:
+*
+* ```
+* * * * * * cd /path/to/app && npx ark schedule:run >> /dev/null 2>&1
+* ```
+*/
+var ScheduleRunCommand = class extends Command {
+	signature = "schedule:run";
+	description = "Run the scheduled tasks that are due.";
+	async handle() {
+		if (!await loadSchedule()) {
+			this.warn("No src/routes/console.ts found — nothing to schedule.");
+			return;
+		}
+		const results = await runDueEvents(/* @__PURE__ */ new Date());
+		if (!results.length) {
+			this.info("No scheduled tasks are ready to run.");
+			return;
+		}
+		for (const result of results) if (result.ran) this.success(`Ran: ${result.description}`);
+		else if (result.error) this.error(`Failed: ${result.description}`);
+		else this.line(`Skipped (${result.skipped}): ${result.description}`);
+		this.info(`${results.filter((r) => r.ran).length} task(s) ran.`);
+	}
+};
+//#endregion
+export { ScheduleRunCommand };

package/dist/commands/ScheduleWorkCommand.d.ts

@@ -0,0 +1,15 @@
+import { Command } from "@h3ravel/musket";
+
+//#region src/commands/ScheduleWorkCommand.d.ts
+/**
+ * Run the scheduler in the foreground, evaluating due tasks at the top of every
+ * minute. Intended for local development so you don't need a system cron entry;
+ * in production use a single `* * * * *` cron running `schedule:run`.
+ */
+declare class ScheduleWorkCommand extends Command {
+  protected signature: string;
+  protected description: string;
+  handle(): Promise<void>;
+}
+//#endregion
+export { ScheduleWorkCommand };

package/dist/commands/ScheduleWorkCommand.js

@@ -0,0 +1,28 @@
+import { t as loadSchedule } from "../loader-zz_XJXwZ.js";
+import { t as runDueEvents } from "../runner-DFEYebtg.js";
+import { Command } from "@h3ravel/musket";
+//#region src/commands/ScheduleWorkCommand.ts
+/**
+* Run the scheduler in the foreground, evaluating due tasks at the top of every
+* minute. Intended for local development so you don't need a system cron entry;
+* in production use a single `* * * * *` cron running `schedule:run`.
+*/
+var ScheduleWorkCommand = class extends Command {
+	signature = "schedule:work";
+	description = "Run the scheduler every minute in the foreground (for local development).";
+	async handle() {
+		if (!await loadSchedule()) {
+			this.warn("No src/routes/console.ts found — nothing to schedule.");
+			return;
+		}
+		this.info("Schedule worker started; evaluating tasks every minute. Press Ctrl+C to stop.");
+		for (;;) {
+			const results = await runDueEvents(/* @__PURE__ */ new Date());
+			for (const result of results) if (result.ran) this.success(`Ran: ${result.description}`);
+			else if (result.error) this.error(`Failed: ${result.description}`);
+			await new Promise((resolve) => setTimeout(resolve, 6e4 - Date.now() % 6e4 + 1e3));
+		}
+	}
+};
+//#endregion
+export { ScheduleWorkCommand };

package/dist/index.d.ts

@@ -0,0 +1,326 @@
+//#region src/types.d.ts
+/** A no-arg task the scheduler runs when an event is due. */
+type TaskCallback = () => void | Promise<void>;
+/** A predicate gating whether a due event actually runs. */
+type FilterCallback = () => boolean | Promise<boolean>;
+/** A lifecycle hook (before/after/onSuccess/onFailure). */
+type HookCallback = (error?: unknown) => void | Promise<void>;
+/** How an event's task is produced — used for `schedule:list` output. */
+type EventType = 'command' | 'call' | 'job' | 'exec';
+/** The result of running one scheduled event. */
+interface RunResult {
+  description: string;
+  expression: string;
+  ran: boolean;
+  /** Why it did not run, when `ran` is false. */
+  skipped?: 'not-due' | 'filtered' | 'overlapping' | 'one-server' | 'environment';
+  error?: unknown;
+}
+//#endregion
+//#region src/ScheduledEvent.d.ts
+/**
+ * A single scheduled task with a fluent builder for its frequency, constraints,
+ * overlap behaviour and lifecycle hooks. Created via the {@link Schedule} facade
+ * (`command`/`call`/`job`/`exec`) and evaluated once a minute by `schedule:run`.
+ */
+declare class ScheduledEvent {
+  readonly type: EventType;
+  private segments;
+  private timezoneValue?;
+  descriptionValue: string;
+  private readonly filters;
+  private readonly rejects;
+  private environmentsValue?;
+  private readonly windows;
+  private readonly beforeHooks;
+  private readonly afterHooks;
+  private readonly successHooks;
+  private readonly failureHooks;
+  private withoutOverlappingValue;
+  private overlapExpiresMinutes;
+  private onOneServerValue;
+  private runInBackgroundValue;
+  private mutexNameValue?;
+  private callTask?;
+  private jobPayload?;
+  private processCommand?;
+  private processArgs;
+  constructor(type: EventType, target: string);
+  setCall(task: TaskCallback): this;
+  setJob(job: unknown): this;
+  setProcess(command: string, args?: string[]): this;
+  /** The 5-field cron expression this event resolves to. */
+  get expression(): string;
+  private splice;
+  cron(expression: string): this;
+  everyMinute(): this;
+  everyTwoMinutes(): this;
+  everyThreeMinutes(): this;
+  everyFourMinutes(): this;
+  everyFiveMinutes(): this;
+  everyTenMinutes(): this;
+  everyFifteenMinutes(): this;
+  everyThirtyMinutes(): this;
+  hourly(): this;
+  hourlyAt(minute: number | number[]): this;
+  everyTwoHours(minute?: number): this;
+  everyOddHour(minute?: number): this;
+  daily(): this;
+  at(time: string): this;
+  dailyAt(time: string): this;
+  twiceDaily(first?: number, second?: number, minute?: number): this;
+  weekly(): this;
+  weeklyOn(day: number | number[], time?: string): this;
+  monthly(): this;
+  monthlyOn(day?: number, time?: string): this;
+  quarterly(): this;
+  yearly(): this;
+  days(day: number | number[]): this;
+  weekdays(): this;
+  weekends(): this;
+  sundays(): this;
+  mondays(): this;
+  tuesdays(): this;
+  wednesdays(): this;
+  thursdays(): this;
+  fridays(): this;
+  saturdays(): this;
+  timezone(timezone: string): this;
+  /**
+   * Only run when every registered `when` predicate is truthy.
+   *
+   * @param callback
+   * @returns
+   */
+  when(callback: FilterCallback): this;
+  /**
+   * Skip when any registered `skip` predicate is truthy.
+   *
+   * @param callback
+   * @returns
+   */
+  skip(callback: FilterCallback): this;
+  /**
+   * Only run in these `APP_ENV` environments.
+   *
+   * @param callback
+   * @returns
+   */
+  environments(...environments: (string | string[])[]): this;
+  /**
+   * Only run when the current time is within `[start, end]` (HH:MM, event tz).
+   *
+   * @param start
+   * @param end
+   * @returns
+   */
+  between(start: string, end: string): this;
+  /**
+   * Only run when the current time is outside `[start, end]`.
+   *
+   * @param callback
+   * @returns
+   */
+  unlessBetween(start: string, end: string): this;
+  private toMinutes;
+  /**
+   * Prevent the task from overlapping itself; the lock expires after `expiresMinutes`.
+   *
+   * @param expiresMinutes
+   * @returns
+   */
+  withoutOverlapping(expiresMinutes?: number): this;
+  /**
+   * Run on only one server per due minute (requires a shared cache store).
+   *
+   * @param callback
+   * @returns
+   */
+  onOneServer(): this;
+  /**
+   * Run the task in a detached background process (command/exec only).
+   *
+   * @param callback
+   * @returns
+   */
+  runInBackground(): this;
+  /**
+   * A human description shown by `schedule:list`.
+   *
+   * @param callback
+   * @returns
+   */
+  description(description: string): this;
+  /**
+   * An explicit mutex name (otherwise derived from the expression + description).
+   *
+   * @param name
+   * @returns
+   */
+  name(name: string): this;
+  before(hook: HookCallback): this;
+  after(hook: HookCallback): this;
+  onSuccess(hook: HookCallback): this;
+  onFailure(hook: HookCallback): this;
+  /**
+   * Whether the cron expression is due at `date`.
+   *
+   * @param date
+   * @returns
+   */
+  isDue(date?: Date): boolean;
+  /**
+   * The next time this event will run after `from`.
+   *
+   * @param date
+   * @returns
+   */
+  nextRunAt(from?: Date): Date | null;
+  /**
+   * Whether environment, time-window, `when` and `skip` constraints all pass.
+   *
+   * @param date
+   * @returns
+   */
+  filtersPass(date?: Date): Promise<boolean>;
+  /**
+   * A stable mutex key derived from the expression + description (or an explicit name).
+   *
+   * @returns
+   */
+  mutexName(): string;
+  /**
+   * Run the task now, honouring overlap/one-server locks and lifecycle hooks.
+   * Assumes the event is already due and its filters pass.
+   *
+   * @param date  The reference moment (used for the one-server per-minute key).
+   */
+  run(date?: Date): Promise<RunResult>;
+  private callHooks;
+  private executeTask;
+  private spawnProcess;
+}
+//#endregion
+//#region src/Schedule.d.ts
+/**
+ * The scheduling facade. Define tasks in `src/routes/console.ts`:
+ *
+ * ```ts
+ * import { Schedule } from '@arkstack/scheduler'
+ *
+ * Schedule.command('report:send').dailyAt('13:00')
+ * Schedule.call(() => prune()).hourly().withoutOverlapping()
+ * Schedule.job(new Heartbeat()).everyFiveMinutes()
+ * Schedule.exec('backup.sh').daily().onOneServer()
+ * ```
+ */
+declare class Schedule {
+  /**
+   * Run an Arkstack CLI command (`ark <name>`) on the schedule.
+   *
+   * @param name
+   * @param args
+   * @returns
+   */
+  static command(name: string, args?: string[]): ScheduledEvent;
+  /**
+   * Run a callback on the schedule.
+   *
+   * @param callback
+   * @returns
+   */
+  static call(callback: TaskCallback): ScheduledEvent;
+  /**
+   * Dispatch a queued job on the schedule (requires `@arkstack/jobs`).
+    *
+    * @param callback
+    * @returns
+    */
+  static job(job: object): ScheduledEvent;
+  /**
+   * Run a shell command on the schedule.
+   *
+   * @param callback
+   * @returns
+   */
+  static exec(command: string, args?: string[]): ScheduledEvent;
+  /**
+   * All registered events.
+   *
+   * @param callback
+   * @returns
+   */
+  static events(): ScheduledEvent[];
+  /**
+   * Events whose cron expression is due at `date`.
+   *
+   * @param callback
+   * @returns
+   */
+  static dueEvents(date?: Date): ScheduledEvent[];
+  /**
+   * Remove all registered events (used in tests).
+   *
+   * @param callback
+   * @returns
+   */
+  static clear(): void;
+  private static add;
+}
+//#endregion
+//#region src/runner.d.ts
+/**
+ * Run every event that is due at `now` and whose filters pass, collecting a
+ * result per event (including the ones skipped by filters or locks).
+ *
+ * @param now  The reference moment (defaults to now).
+ */
+declare const runDueEvents: (now?: Date) => Promise<RunResult[]>;
+//#endregion
+//#region src/loader.d.ts
+/**
+ * Load the application's schedule definitions from `src/routes/console.ts`.
+ * The TypeScript source is preferred (loaded via jiti, so no build is needed),
+ * falling back to the built `<outDir>/routes/console.js`.
+ *
+ * @returns `true` when a console route file was found and loaded.
+ */
+declare const loadSchedule: () => Promise<boolean>;
+//#endregion
+//#region src/cron.d.ts
+/**
+ * Whether a cron expression is due at the given moment (minute resolution).
+ *
+ * Uses croner to find the next run at/after one second before `date`; the
+ * expression is due when that run falls in the same minute as `date`.
+ *
+ * @param expression  A 5-field cron expression.
+ * @param date        The moment to test (defaults to now).
+ * @param timezone    IANA timezone the expression is evaluated in.
+ */
+declare const isDue: (expression: string, date?: Date, timezone?: string) => boolean;
+/**
+ * The next time a cron expression will run after `from`.
+ *
+ * @param expression  A 5-field cron expression.
+ * @param from        The reference moment (defaults to now).
+ * @param timezone    IANA timezone the expression is evaluated in.
+ */
+declare const nextRun: (expression: string, from?: Date, timezone?: string) => Date | null;
+//#endregion
+//#region src/locks.d.ts
+/**
+ * Try to acquire a lock. Returns `true` when acquired, `false` when already held.
+ *
+ * @param key         The lock key.
+ * @param ttlSeconds  How long the lock is held before it auto-expires.
+ */
+declare const acquireLock: (key: string, ttlSeconds: number) => Promise<boolean>;
+/**
+ * Release a previously acquired lock.
+ *
+ * @param key  The lock key.
+ */
+declare const releaseLock: (key: string) => Promise<void>;
+//#endregion
+export { EventType, FilterCallback, HookCallback, RunResult, Schedule, ScheduledEvent, TaskCallback, acquireLock, isDue, loadSchedule, nextRun, releaseLock, runDueEvents };

package/dist/index.js

@@ -0,0 +1,3 @@
+import { a as nextRun, i as isDue, n as Schedule, o as acquireLock, r as ScheduledEvent, s as releaseLock, t as loadSchedule } from "./loader-zz_XJXwZ.js";
+import { t as runDueEvents } from "./runner-DFEYebtg.js";
+export { Schedule, ScheduledEvent, acquireLock, isDue, loadSchedule, nextRun, releaseLock, runDueEvents };