@arkstack/scheduler 0.19.2 → 0.19.3

package/README.md

@@ -18,19 +18,19 @@ Full app templates include it and a `src/routes/console.ts` already.
 In `src/routes/console.ts`:
 
 ```ts
-import { Schedule } from '@arkstack/scheduler';
+import { Schedule } from '@arkstack/scheduler'
 
-Schedule.command('cache:prune').hourly();
+Schedule.command('cache:prune').hourly()
 
 Schedule.call(async () => {
-  await pruneTempFiles();
+  await pruneTempFiles()
 })
   .dailyAt('01:30')
-  .withoutOverlapping();
+  .withoutOverlapping()
 
-Schedule.job(new SendDigest()).weeklyOn(1, '08:00');
+Schedule.job(new SendDigest()).weeklyOn(1, '08:00')
 
-Schedule.exec('backup.sh').daily().onOneServer();
+Schedule.exec('backup.sh').daily().onOneServer()
 ```
 
 | Task type                       | Runs                                           |
@@ -58,36 +58,36 @@ 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
+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
+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');
+Schedule.command('x').dailyAt('09:00').timezone('America/New_York')
 ```
 
 ## Constraints
@@ -98,7 +98,7 @@ Schedule.command('x')
   .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
+  .between('09:00', '17:00') // only within a daily window
 ```
 
 `unlessBetween('22:00', '06:00')` runs _outside_ a window (overnight ranges handled).
@@ -106,9 +106,9 @@ Schedule.command('x')
 ## Overlaps, single-server & background
 
 ```ts
-Schedule.command('report:build').everyFiveMinutes().withoutOverlapping();
-Schedule.exec('backup.sh').daily().onOneServer();
-Schedule.exec('long-import.sh').daily().runInBackground();
+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.
@@ -121,7 +121,7 @@ Schedule.command('report:build')
   .before(() => logger.info('building report'))
   .onSuccess(() => notifyOk())
   .onFailure((error) => notifyFailed(error))
-  .after(() => logger.info('done'));
+  .after(() => logger.info('done'))
 ```
 
 ## API

package/dist/commands/ScheduleListCommand.js

@@ -1,4 +1,4 @@
-import { n as Schedule, t as loadSchedule } from "../loader-CZcEYUX9.js";
+import { n as Schedule, t as loadSchedule } from "../loader-DlxdvHFL.js";
 import { Command } from "@h3ravel/musket";
 //#region src/commands/ScheduleListCommand.ts
 /**

package/dist/commands/ScheduleRunCommand.js

@@ -1,5 +1,5 @@
-import { t as loadSchedule } from "../loader-CZcEYUX9.js";
-import { t as runDueEvents } from "../runner-Bt-jQptE.js";
+import { t as loadSchedule } from "../loader-DlxdvHFL.js";
+import { t as runDueEvents } from "../runner-b2r6TZPd.js";
 import { Command } from "@h3ravel/musket";
 //#region src/commands/ScheduleRunCommand.ts
 /**

package/dist/commands/ScheduleWorkCommand.js

@@ -1,5 +1,5 @@
-import { t as loadSchedule } from "../loader-CZcEYUX9.js";
-import { t as runDueEvents } from "../runner-Bt-jQptE.js";
+import { t as loadSchedule } from "../loader-DlxdvHFL.js";
+import { t as runDueEvents } from "../runner-b2r6TZPd.js";
 import { Command } from "@h3ravel/musket";
 //#region src/commands/ScheduleWorkCommand.ts
 /**

package/dist/index.js

@@ -1,3 +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-CZcEYUX9.js";
-import { t as runDueEvents } from "./runner-Bt-jQptE.js";
+import { a as nextRun, i as isDue, n as Schedule, o as acquireLock, r as ScheduledEvent, s as releaseLock, t as loadSchedule } from "./loader-DlxdvHFL.js";
+import { t as runDueEvents } from "./runner-b2r6TZPd.js";
 export { Schedule, ScheduledEvent, acquireLock, isDue, loadSchedule, nextRun, releaseLock, runDueEvents };

package/dist/{loader-CZcEYUX9.js → loader-DlxdvHFL.js}

@@ -280,42 +280,42 @@ var ScheduledEvent = class {
 		this.timezoneValue = timezone;
 		return this;
 	}
-	/** 
+	/**
 	* Only run when every registered `when` predicate is truthy.
-	* 
-	* @param callback 
-	* @returns 
+	*
+	* @param callback
+	* @returns
 	*/
 	when(callback) {
 		this.filters.push(callback);
 		return this;
 	}
-	/** 
+	/**
 	* Skip when any registered `skip` predicate is truthy.
-	* 
-	* @param callback 
-	* @returns 
+	*
+	* @param callback
+	* @returns
 	*/
 	skip(callback) {
 		this.rejects.push(callback);
 		return this;
 	}
-	/** 
+	/**
 	* Only run in these `APP_ENV` environments.
-	* 
-	* @param callback 
-	* @returns 
+	*
+	* @param callback
+	* @returns
 	*/
 	environments(...environments) {
 		this.environmentsValue = environments.flat();
 		return this;
 	}
-	/** 
-	* Only run when the current time is within `[start, end]` (HH:MM, event tz). 
-	* 
-	* @param start 
-	* @param end 
-	* @returns 
+	/**
+	* Only run when the current time is within `[start, end]` (HH:MM, event tz).
+	*
+	* @param start
+	* @param end
+	* @returns
 	*/
 	between(start, end) {
 		this.windows.push({
@@ -325,11 +325,11 @@ var ScheduledEvent = class {
 		});
 		return this;
 	}
-	/** 
+	/**
 	* Only run when the current time is outside `[start, end]`.
-	* 
-	* @param callback 
-	* @returns 
+	*
+	* @param callback
+	* @returns
 	*/
 	unlessBetween(start, end) {
 		this.windows.push({
@@ -343,52 +343,52 @@ var ScheduledEvent = class {
 		const [h, m] = parseTime(time);
 		return h * 60 + m;
 	}
-	/** 
-	* Prevent the task from overlapping itself; the lock expires after `expiresMinutes`. 
-	* 
-	* @param expiresMinutes 
-	* @returns 
+	/**
+	* Prevent the task from overlapping itself; the lock expires after `expiresMinutes`.
+	*
+	* @param expiresMinutes
+	* @returns
 	*/
 	withoutOverlapping(expiresMinutes = 1440) {
 		this.withoutOverlappingValue = true;
 		this.overlapExpiresMinutes = expiresMinutes;
 		return this;
 	}
-	/** 
+	/**
 	* Run on only one server per due minute (requires a shared cache store).
-	* 
-	* @param callback 
-	* @returns 
+	*
+	* @param callback
+	* @returns
 	*/
 	onOneServer() {
 		this.onOneServerValue = true;
 		return this;
 	}
-	/** 
+	/**
 	* Run the task in a detached background process (command/exec only).
-	* 
-	* @param callback 
-	* @returns 
+	*
+	* @param callback
+	* @returns
 	*/
 	runInBackground() {
 		this.runInBackgroundValue = true;
 		return this;
 	}
-	/** 
+	/**
 	* A human description shown by `schedule:list`.
-	* 
-	* @param callback 
-	* @returns 
+	*
+	* @param callback
+	* @returns
 	*/
 	description(description) {
 		this.descriptionValue = description;
 		return this;
 	}
-	/** 
+	/**
 	* An explicit mutex name (otherwise derived from the expression + description).  
-	* 
-	* @param name 
-	* @returns 
+	*
+	* @param name
+	* @returns
 	*/
 	name(name) {
 		this.mutexNameValue = name;
@@ -410,29 +410,29 @@ var ScheduledEvent = class {
 		this.failureHooks.push(hook);
 		return this;
 	}
-	/** 
-	* Whether the cron expression is due at `date`. 
-	* 
-	* @param date 
-	* @returns 
+	/**
+	* Whether the cron expression is due at `date`.
+	*
+	* @param date
+	* @returns
 	*/
 	isDue(date = /* @__PURE__ */ new Date()) {
 		return isDue(this.expression, date, this.timezoneValue);
 	}
-	/** 
-	* The next time this event will run after `from`. 
-	* 
-	* @param date 
-	* @returns 
+	/**
+	* The next time this event will run after `from`.
+	*
+	* @param date
+	* @returns
 	*/
 	nextRunAt(from = /* @__PURE__ */ new Date()) {
 		return nextRun(this.expression, from, this.timezoneValue);
 	}
-	/** 
-	* Whether environment, time-window, `when` and `skip` constraints all pass. 
-	* 
-	* @param date 
-	* @returns 
+	/**
+	* Whether environment, time-window, `when` and `skip` constraints all pass.
+	*
+	* @param date
+	* @returns
 	*/
 	async filtersPass(date = /* @__PURE__ */ new Date()) {
 		if (this.environmentsValue) {
@@ -447,10 +447,10 @@ var ScheduledEvent = class {
 		for (const reject of this.rejects) if (await reject()) return false;
 		return true;
 	}
-	/** 
+	/**
 	* A stable mutex key derived from the expression + description (or an explicit name).  
-	* 
-	* @returns 
+	*
+	* @returns
 	*/
 	mutexName() {
 		if (this.mutexNameValue) return `arkstack-schedule-${this.mutexNameValue}`;
@@ -568,70 +568,70 @@ const registry = () => {
 * ```
 */
 var Schedule = class {
-	/** 
+	/**
 	* Run an Arkstack CLI command (`ark <name>`) on the schedule.  
-	* 
-	* @param name 
-	* @param args 
-	* @returns 
+	*
+	* @param name
+	* @param args
+	* @returns
 	*/
 	static command(name, args = []) {
 		const event = new ScheduledEvent("command", `ark ${name}`).setProcess(name, args);
 		return this.add(event);
 	}
-	/** 
-	* Run a callback on the schedule. 
-	* 
-	* @param callback 
-	* @returns 
+	/**
+	* Run a callback on the schedule.
+	*
+	* @param callback
+	* @returns
 	*/
 	static call(callback) {
 		const event = new ScheduledEvent("call", "Closure").setCall(callback);
 		return this.add(event);
 	}
-	/** 
-	* Dispatch a queued job on the schedule (requires `@arkstack/jobs`). 
-	* 
-	* @param callback 
-	* @returns 
+	/**
+	* Dispatch a queued job on the schedule (requires `@arkstack/jobs`).
+	*
+	* @param callback
+	* @returns
 	*/
 	static job(job) {
 		const event = new ScheduledEvent("job", job?.constructor?.name ?? "Job").setJob(job);
 		return this.add(event);
 	}
-	/** 
-	* Run a shell command on the schedule. 
-	* 
-	* @param callback 
-	* @returns 
+	/**
+	* Run a shell command on the schedule.
+	*
+	* @param callback
+	* @returns
 	*/
 	static exec(command, args = []) {
 		const event = new ScheduledEvent("exec", [command, ...args].join(" ")).setProcess(command, args);
 		return this.add(event);
 	}
-	/** 
-	* All registered events. 
-	* 
-	* @param callback 
-	* @returns 
+	/**
+	* All registered events.
+	*
+	* @param callback
+	* @returns
 	*/
 	static events() {
 		return registry();
 	}
-	/** 
-	* Events whose cron expression is due at `date`. 
-	* 
-	* @param callback 
-	* @returns 
+	/**
+	* Events whose cron expression is due at `date`.
+	*
+	* @param callback
+	* @returns
 	*/
 	static dueEvents(date = /* @__PURE__ */ new Date()) {
 		return registry().filter((event) => event.isDue(date));
 	}
-	/** 
-	* Remove all registered events (used in tests). 
-	* 
-	* @param callback 
-	* @returns 
+	/**
+	* Remove all registered events (used in tests).
+	*
+	* @param callback
+	* @returns
 	*/
 	static clear() {
 		registry().length = 0;

package/dist/{runner-Bt-jQptE.js → runner-b2r6TZPd.js}

@@ -1,4 +1,4 @@
-import { n as Schedule } from "./loader-CZcEYUX9.js";
+import { n as Schedule } from "./loader-DlxdvHFL.js";
 //#region src/runner.ts
 /**
 * Run every event that is due at `now` and whose filters pass, collecting a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkstack/scheduler",
-  "version": "0.19.2",
+  "version": "0.19.3",
   "type": "module",
   "description": "Task scheduling for Arkstack: fluent frequencies, cron, overlap/one-server locks, hooks, and schedule:run/work/list commands.",
   "homepage": "https://arkstack.toneflix.net/guide/scheduling",
@@ -33,13 +33,13 @@
   },
   "dependencies": {
     "croner": "^9.0.0",
-    "@arkstack/common": "^0.19.2"
+    "@arkstack/common": "^0.19.3"
   },
   "peerDependencies": {
     "@h3ravel/musket": "^2.2.13",
-    "@arkstack/contract": "^0.19.2",
-    "@arkstack/jobs": "^0.19.2",
-    "@arkstack/cache": "^0.19.2"
+    "@arkstack/contract": "^0.19.3",
+    "@arkstack/jobs": "^0.19.3",
+    "@arkstack/cache": "^0.19.3"
   },
   "peerDependenciesMeta": {
     "@arkstack/cache": {