@arkstack/scheduler 0.17.0

package/dist/loader-zz_XJXwZ.js

@@ -0,0 +1,666 @@
+import { Cron } from "croner";
+import { Arkstack } from "@arkstack/contract";
+import { createHash } from "node:crypto";
+import { env, importFile, outputDir } from "@arkstack/common";
+import path, { join } from "node:path";
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+//#region src/locks.ts
+/**
+* Mutual-exclusion helpers backing `withoutOverlapping()` and `onOneServer()`.
+*
+* Locks are stored in `@arkstack/cache` (an optional peer) so they coordinate
+* across processes and servers. When cache is unavailable the scheduler degrades
+* to a process-local lock — enough to prevent overlap within one process, but it
+* cannot coordinate across servers.
+*/
+const memoryLocks = /* @__PURE__ */ new Map();
+/** Resolve the cache manager, or `null` when `@arkstack/cache` isn't installed. */
+const cache = async () => {
+	try {
+		return (await import("@arkstack/cache")).Cache ?? null;
+	} catch {
+		return null;
+	}
+};
+/**
+* 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.
+*/
+const acquireLock = async (key, ttlSeconds) => {
+	const store = await cache();
+	if (store) try {
+		return await store.add(key, (/* @__PURE__ */ new Date()).toISOString(), ttlSeconds);
+	} catch {}
+	const now = Date.now();
+	const expiry = memoryLocks.get(key);
+	if (expiry && expiry > now) return false;
+	memoryLocks.set(key, now + ttlSeconds * 1e3);
+	return true;
+};
+/**
+* Release a previously acquired lock.
+*
+* @param key  The lock key.
+*/
+const releaseLock = async (key) => {
+	const store = await cache();
+	if (store) try {
+		await store.forget(key);
+		return;
+	} catch {}
+	memoryLocks.delete(key);
+};
+//#endregion
+//#region src/cron.ts
+/** Truncate a date to its minute (scheduler resolution is one minute). */
+const toMinute = (date) => Math.floor(date.getTime() / 6e4);
+/**
+* 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.
+*/
+const isDue = (expression, date = /* @__PURE__ */ new Date(), timezone) => {
+	try {
+		const next = new Cron(expression, timezone ? { timezone } : {}).nextRun(/* @__PURE__ */ new Date(date.getTime() - 1e3));
+		return !!next && toMinute(next) === toMinute(date);
+	} catch {
+		return false;
+	}
+};
+/**
+* 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.
+*/
+const nextRun = (expression, from = /* @__PURE__ */ new Date(), timezone) => {
+	try {
+		return new Cron(expression, timezone ? { timezone } : {}).nextRun(from);
+	} catch {
+		return null;
+	}
+};
+//#endregion
+//#region src/ScheduledEvent.ts
+const DAYS = {
+	sunday: 0,
+	monday: 1,
+	tuesday: 2,
+	wednesday: 3,
+	thursday: 4,
+	friday: 5,
+	saturday: 6
+};
+/** Parse `HH:MM` into `[hour, minute]`. */
+const parseTime = (time) => {
+	const [h, m] = time.split(":");
+	return [Number(h ?? 0), Number(m ?? 0)];
+};
+/** Minutes-from-midnight for `date`, in the given timezone. */
+const minutesOfDay = (date, timezone) => {
+	const parts = new Intl.DateTimeFormat("en-US", {
+		hour: "2-digit",
+		minute: "2-digit",
+		hour12: false,
+		timeZone: timezone
+	}).formatToParts(date);
+	const hour = Number(parts.find((p) => p.type === "hour")?.value ?? 0) % 24;
+	const minute = Number(parts.find((p) => p.type === "minute")?.value ?? 0);
+	return hour * 60 + minute;
+};
+/**
+* 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`.
+*/
+var ScheduledEvent = class {
+	type;
+	segments = [
+		"*",
+		"*",
+		"*",
+		"*",
+		"*"
+	];
+	timezoneValue;
+	descriptionValue;
+	filters = [];
+	rejects = [];
+	environmentsValue;
+	windows = [];
+	beforeHooks = [];
+	afterHooks = [];
+	successHooks = [];
+	failureHooks = [];
+	withoutOverlappingValue = false;
+	overlapExpiresMinutes = 1440;
+	onOneServerValue = false;
+	runInBackgroundValue = false;
+	mutexNameValue;
+	callTask;
+	jobPayload;
+	processCommand;
+	processArgs = [];
+	constructor(type, target) {
+		this.type = type;
+		this.descriptionValue = target;
+	}
+	setCall(task) {
+		this.callTask = task;
+		return this;
+	}
+	setJob(job) {
+		this.jobPayload = job;
+		return this;
+	}
+	setProcess(command, args = []) {
+		this.processCommand = command;
+		this.processArgs = args;
+		return this;
+	}
+	/** The 5-field cron expression this event resolves to. */
+	get expression() {
+		return this.segments.join(" ");
+	}
+	splice(position, value) {
+		this.segments[position - 1] = String(value);
+		return this;
+	}
+	cron(expression) {
+		this.segments = expression.trim().split(/\s+/).slice(0, 5);
+		while (this.segments.length < 5) this.segments.push("*");
+		return this;
+	}
+	everyMinute() {
+		return this.splice(1, "*");
+	}
+	everyTwoMinutes() {
+		return this.splice(1, "*/2");
+	}
+	everyThreeMinutes() {
+		return this.splice(1, "*/3");
+	}
+	everyFourMinutes() {
+		return this.splice(1, "*/4");
+	}
+	everyFiveMinutes() {
+		return this.splice(1, "*/5");
+	}
+	everyTenMinutes() {
+		return this.splice(1, "*/10");
+	}
+	everyFifteenMinutes() {
+		return this.splice(1, "*/15");
+	}
+	everyThirtyMinutes() {
+		return this.splice(1, "0,30");
+	}
+	hourly() {
+		return this.splice(1, 0);
+	}
+	hourlyAt(minute) {
+		return this.splice(1, Array.isArray(minute) ? minute.join(",") : minute);
+	}
+	everyTwoHours(minute = 0) {
+		return this.splice(1, minute).splice(2, "*/2");
+	}
+	everyOddHour(minute = 0) {
+		return this.splice(1, minute).splice(2, "1-23/2");
+	}
+	daily() {
+		return this.splice(1, 0).splice(2, 0);
+	}
+	at(time) {
+		return this.dailyAt(time);
+	}
+	dailyAt(time) {
+		const [hour, minute] = parseTime(time);
+		return this.splice(1, minute).splice(2, hour);
+	}
+	twiceDaily(first = 1, second = 13, minute = 0) {
+		return this.splice(1, minute).splice(2, `${first},${second}`);
+	}
+	weekly() {
+		return this.splice(1, 0).splice(2, 0).splice(5, 0);
+	}
+	weeklyOn(day, time = "0:0") {
+		this.dailyAt(time);
+		return this.splice(5, Array.isArray(day) ? day.join(",") : day);
+	}
+	monthly() {
+		return this.splice(1, 0).splice(2, 0).splice(3, 1);
+	}
+	monthlyOn(day = 1, time = "0:0") {
+		this.dailyAt(time);
+		return this.splice(3, day);
+	}
+	quarterly() {
+		return this.splice(1, 0).splice(2, 0).splice(3, 1).splice(4, "1-12/3");
+	}
+	yearly() {
+		return this.splice(1, 0).splice(2, 0).splice(3, 1).splice(4, 1);
+	}
+	days(day) {
+		return this.splice(5, Array.isArray(day) ? day.join(",") : day);
+	}
+	weekdays() {
+		return this.splice(5, "1-5");
+	}
+	weekends() {
+		return this.splice(5, "0,6");
+	}
+	sundays() {
+		return this.splice(5, DAYS.sunday);
+	}
+	mondays() {
+		return this.splice(5, DAYS.monday);
+	}
+	tuesdays() {
+		return this.splice(5, DAYS.tuesday);
+	}
+	wednesdays() {
+		return this.splice(5, DAYS.wednesday);
+	}
+	thursdays() {
+		return this.splice(5, DAYS.thursday);
+	}
+	fridays() {
+		return this.splice(5, DAYS.friday);
+	}
+	saturdays() {
+		return this.splice(5, DAYS.saturday);
+	}
+	timezone(timezone) {
+		this.timezoneValue = timezone;
+		return this;
+	}
+	/** 
+	* Only run when every registered `when` predicate is truthy.
+	* 
+	* @param callback 
+	* @returns 
+	*/
+	when(callback) {
+		this.filters.push(callback);
+		return this;
+	}
+	/** 
+	* Skip when any registered `skip` predicate is truthy.
+	* 
+	* @param callback 
+	* @returns 
+	*/
+	skip(callback) {
+		this.rejects.push(callback);
+		return this;
+	}
+	/** 
+	* Only run in these `APP_ENV` environments.
+	* 
+	* @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 
+	*/
+	between(start, end) {
+		this.windows.push({
+			start: this.toMinutes(start),
+			end: this.toMinutes(end),
+			negate: false
+		});
+		return this;
+	}
+	/** 
+	* Only run when the current time is outside `[start, end]`.
+	* 
+	* @param callback 
+	* @returns 
+	*/
+	unlessBetween(start, end) {
+		this.windows.push({
+			start: this.toMinutes(start),
+			end: this.toMinutes(end),
+			negate: true
+		});
+		return this;
+	}
+	toMinutes(time) {
+		const [h, m] = parseTime(time);
+		return h * 60 + m;
+	}
+	/** 
+	* 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 
+	*/
+	onOneServer() {
+		this.onOneServerValue = true;
+		return this;
+	}
+	/** 
+	* Run the task in a detached background process (command/exec only).
+	* 
+	* @param callback 
+	* @returns 
+	*/
+	runInBackground() {
+		this.runInBackgroundValue = true;
+		return this;
+	}
+	/** 
+	* A human description shown by `schedule:list`.
+	* 
+	* @param callback 
+	* @returns 
+	*/
+	description(description) {
+		this.descriptionValue = description;
+		return this;
+	}
+	/** 
+	* An explicit mutex name (otherwise derived from the expression + description).  
+	* 
+	* @param name 
+	* @returns 
+	*/
+	name(name) {
+		this.mutexNameValue = name;
+		return this;
+	}
+	before(hook) {
+		this.beforeHooks.push(hook);
+		return this;
+	}
+	after(hook) {
+		this.afterHooks.push(hook);
+		return this;
+	}
+	onSuccess(hook) {
+		this.successHooks.push(hook);
+		return this;
+	}
+	onFailure(hook) {
+		this.failureHooks.push(hook);
+		return this;
+	}
+	/** 
+	* 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 
+	*/
+	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 
+	*/
+	async filtersPass(date = /* @__PURE__ */ new Date()) {
+		if (this.environmentsValue) {
+			const current = String(env("APP_ENV", "") || "");
+			if (!this.environmentsValue.includes(current)) return false;
+		}
+		for (const window of this.windows) {
+			const now = minutesOfDay(date, this.timezoneValue);
+			if ((window.start <= window.end ? now >= window.start && now <= window.end : now >= window.start || now <= window.end) === window.negate) return false;
+		}
+		for (const filter of this.filters) if (!await filter()) return false;
+		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 
+	*/
+	mutexName() {
+		if (this.mutexNameValue) return `arkstack-schedule-${this.mutexNameValue}`;
+		return `arkstack-schedule-${createHash("sha1").update(`${this.type}:${this.expression}:${this.descriptionValue}`).digest("hex")}`;
+	}
+	/**
+	* 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).
+	*/
+	async run(date = /* @__PURE__ */ new Date()) {
+		const base = {
+			description: this.descriptionValue,
+			expression: this.expression
+		};
+		if (this.onOneServerValue) {
+			const minute = Math.floor(date.getTime() / 6e4);
+			if (!await acquireLock(`${this.mutexName()}-server-${minute}`, 60)) return {
+				...base,
+				ran: false,
+				skipped: "one-server"
+			};
+		}
+		let overlapKey;
+		if (this.withoutOverlappingValue) {
+			overlapKey = this.mutexName();
+			if (!await acquireLock(overlapKey, this.overlapExpiresMinutes * 60)) return {
+				...base,
+				ran: false,
+				skipped: "overlapping"
+			};
+		}
+		let error;
+		try {
+			await this.callHooks(this.beforeHooks);
+			await this.executeTask();
+			await this.callHooks(this.successHooks);
+		} catch (caught) {
+			error = caught;
+			await this.callHooks(this.failureHooks, caught);
+		} finally {
+			await this.callHooks(this.afterHooks, error);
+			if (overlapKey && !this.runInBackgroundValue) await releaseLock(overlapKey);
+		}
+		return {
+			...base,
+			ran: !error,
+			error
+		};
+	}
+	async callHooks(hooks, error) {
+		for (const hook of hooks) await hook(error);
+	}
+	async executeTask() {
+		switch (this.type) {
+			case "call":
+				await this.callTask?.();
+				return;
+			case "job": {
+				const { dispatch } = await import("@arkstack/jobs");
+				await dispatch(this.jobPayload);
+				return;
+			}
+			case "command": {
+				const consoleEntry = join(Arkstack.rootDir(), "node_modules", "@arkstack", "console", "dist", "index.js");
+				await this.spawnProcess(process.execPath, [
+					consoleEntry,
+					...this.processCommand ? [this.processCommand] : [],
+					...this.processArgs
+				]);
+				return;
+			}
+			case "exec":
+				await this.spawnProcess(this.processCommand ?? "", this.processArgs, true);
+				return;
+		}
+	}
+	spawnProcess(command, args, shell = false) {
+		return new Promise((resolve, reject) => {
+			const child = spawn(command, args, {
+				cwd: Arkstack.rootDir(),
+				shell,
+				detached: this.runInBackgroundValue,
+				stdio: this.runInBackgroundValue ? "ignore" : "inherit"
+			});
+			if (this.runInBackgroundValue) {
+				child.unref();
+				resolve();
+				return;
+			}
+			child.on("error", reject);
+			child.on("exit", (code) => code === 0 ? resolve() : reject(/* @__PURE__ */ new Error(`Scheduled process exited with code ${code}`)));
+		});
+	}
+};
+//#endregion
+//#region src/Schedule.ts
+const REGISTRY = Symbol.for("arkstack.scheduler.events");
+const registry = () => {
+	const store = globalThis;
+	return store[REGISTRY] ??= [];
+};
+/**
+* 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()
+* ```
+*/
+var Schedule = class {
+	/** 
+	* Run an Arkstack CLI command (`ark <name>`) on the schedule.  
+	* 
+	* @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 
+	*/
+	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 
+	*/
+	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 
+	*/
+	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 
+	*/
+	static events() {
+		return registry();
+	}
+	/** 
+	* 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 
+	*/
+	static clear() {
+		registry().length = 0;
+	}
+	static add(event) {
+		registry().push(event);
+		return event;
+	}
+};
+//#endregion
+//#region src/loader.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.
+*/
+const loadSchedule = async () => {
+	const root = Arkstack.rootDir();
+	const dist = path.relative(root, outputDir());
+	const candidates = [join(root, "src", "routes", "console.ts"), join(root, dist, "routes", "console.js")];
+	for (const file of candidates) if (existsSync(file)) {
+		await importFile(file);
+		return true;
+	}
+	return false;
+};
+//#endregion
+export { nextRun as a, isDue as i, Schedule as n, acquireLock as o, ScheduledEvent as r, releaseLock as s, loadSchedule as t };

package/dist/runner-DFEYebtg.js

@@ -0,0 +1,26 @@
+import { n as Schedule } from "./loader-zz_XJXwZ.js";
+//#region src/runner.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).
+*/
+const runDueEvents = async (now = /* @__PURE__ */ new Date()) => {
+	const results = [];
+	for (const event of Schedule.dueEvents(now)) {
+		if (!await event.filtersPass(now)) {
+			results.push({
+				description: event.descriptionValue,
+				expression: event.expression,
+				ran: false,
+				skipped: "filtered"
+			});
+			continue;
+		}
+		results.push(await event.run(now));
+	}
+	return results;
+};
+//#endregion
+export { runDueEvents as t };

package/dist/setup.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/setup.js

@@ -0,0 +1,21 @@
+import { Publisher } from "@arkstack/common";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/setup.ts
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+/**
+* Register the artifacts `@arkstack/scheduler` publishes into the application.
+*
+* Run `ark publish --package @arkstack/scheduler` to copy the starter
+* `src/routes/console.ts` schedule file into the app.
+*/
+Publisher.publishes({
+	package: "@arkstack/scheduler",
+	tag: "scheduler-routes",
+	entries: [{
+		from: join(root, "stubs/routes/console.ts.stub"),
+		to: "src/routes/console.ts"
+	}]
+});
+//#endregion
+export {};