@warlock.js/scheduler 4.0.174 → 4.1.1

package/cjs/index.cjs

@@ -0,0 +1,1132 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+//#region \0rolldown/runtime.js
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") {
+		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+			key = keys[i];
+			if (!__hasOwnProp.call(to, key) && key !== except) {
+				__defProp(to, key, {
+					get: ((k) => from[k]).bind(null, key),
+					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+				});
+			}
+		}
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+let dayjs = require("dayjs");
+dayjs = __toESM(dayjs, 1);
+let dayjs_plugin_isSameOrAfter_js = require("dayjs/plugin/isSameOrAfter.js");
+dayjs_plugin_isSameOrAfter_js = __toESM(dayjs_plugin_isSameOrAfter_js, 1);
+let dayjs_plugin_timezone_js = require("dayjs/plugin/timezone.js");
+dayjs_plugin_timezone_js = __toESM(dayjs_plugin_timezone_js, 1);
+let dayjs_plugin_utc_js = require("dayjs/plugin/utc.js");
+dayjs_plugin_utc_js = __toESM(dayjs_plugin_utc_js, 1);
+let node_events = require("node:events");
+
+//#region ../../@warlock.js/scheduler/src/cron-parser.ts
+/**
+* Cron expression parser
+*
+* Supports standard 5-field cron expressions:
+* ```
+* ┌───────────── minute (0-59)
+* │ ┌───────────── hour (0-23)
+* │ │ ┌───────────── day of month (1-31)
+* │ │ │ ┌───────────── month (1-12)
+* │ │ │ │ ┌───────────── day of week (0-6, Sunday = 0)
+* │ │ │ │ │
+* * * * * *
+* ```
+*
+* Supports:
+* - `*` - any value
+* - `5` - specific value
+* - `1,3,5` - list of values
+* - `1-5` - range of values
+* - `*‍/5` - step values (every 5)
+* - `1-10/2` - range with step
+*
+* **Day-of-month / day-of-week semantics:** follows Vixie cron — when both
+* fields are restricted (neither is `*`), a date matches if it satisfies
+* EITHER constraint. When only one is restricted, the other is ignored.
+*
+* @example
+* ```typescript
+* const parser = new CronParser("0 9 * * 1-5"); // 9 AM weekdays
+* const nextRun = parser.nextRun();
+* ```
+*/
+var CronParser = class {
+	/**
+	* Creates a new CronParser instance
+	*
+	* @param expression - Standard 5-field cron expression
+	* @throws Error if expression is invalid
+	*/
+	constructor(_expression) {
+		this._expression = _expression;
+		const parts = _expression.trim().split(/\s+/);
+		if (parts.length !== 5) throw new Error(`Invalid cron expression: "${_expression}". Expected 5 fields (minute hour day month weekday).`);
+		const [minute, hour, dayOfMonth, month, dayOfWeek] = parts;
+		this._isDayOfMonthRestricted = dayOfMonth.trim() !== "*";
+		this._isDayOfWeekRestricted = dayOfWeek.trim() !== "*";
+		this._fields = {
+			minutes: this._parseField(minute, 0, 59),
+			hours: this._parseField(hour, 0, 23),
+			daysOfMonth: this._parseField(dayOfMonth, 1, 31),
+			months: this._parseField(month, 1, 12),
+			daysOfWeek: this._parseField(dayOfWeek, 0, 6)
+		};
+		this._assertSatisfiable();
+	}
+	/**
+	* Get the parsed cron fields
+	*/
+	get fields() {
+		return this._fields;
+	}
+	/**
+	* Get the original expression
+	*/
+	get expression() {
+		return this._expression;
+	}
+	/**
+	* Calculate the next run time from a given date
+	*
+	* @param from - Starting date (defaults to now)
+	* @returns Next run time as Dayjs
+	*/
+	nextRun(from = (0, dayjs.default)()) {
+		let date = from.add(1, "minute").second(0).millisecond(0);
+		const maxIterations = 366 * 24 * 60;
+		let iterations = 0;
+		while (iterations < maxIterations) {
+			iterations++;
+			if (!this._fields.months.includes(date.month() + 1)) {
+				date = date.add(1, "month").date(1).hour(0).minute(0);
+				continue;
+			}
+			if (!this._dayMatches(date)) {
+				date = date.add(1, "day").hour(0).minute(0);
+				continue;
+			}
+			if (!this._fields.hours.includes(date.hour())) {
+				date = date.add(1, "hour").minute(0);
+				continue;
+			}
+			if (!this._fields.minutes.includes(date.minute())) {
+				date = date.add(1, "minute");
+				continue;
+			}
+			return date;
+		}
+		throw new Error(`Could not find next run time for cron expression: ${this._expression}`);
+	}
+	/**
+	* Check if a given date matches the cron expression
+	*
+	* @param date - Date to check
+	* @returns true if the date matches
+	*/
+	matches(date) {
+		return this._fields.minutes.includes(date.minute()) && this._fields.hours.includes(date.hour()) && this._fields.months.includes(date.month() + 1) && this._dayMatches(date);
+	}
+	/**
+	* Day-of-month / day-of-week match using Vixie cron semantics.
+	*
+	* When both fields are restricted (neither was `*`), a date matches if
+	* EITHER the day-of-month or the day-of-week matches. When only one is
+	* restricted, only that one needs to match (the other is the full set
+	* by construction, so AND degenerates to the restricted one).
+	*/
+	_dayMatches(date) {
+		const dayOfMonthMatches = this._fields.daysOfMonth.includes(date.date());
+		const dayOfWeekMatches = this._fields.daysOfWeek.includes(date.day());
+		if (this._isDayOfMonthRestricted && this._isDayOfWeekRestricted) return dayOfMonthMatches || dayOfWeekMatches;
+		return dayOfMonthMatches && dayOfWeekMatches;
+	}
+	/**
+	* Reject expressions whose day-of-month / month combination can never occur
+	* (e.g. `0 0 30 2 *` — February never has a 30th).
+	*
+	* Without this guard, `nextRun()` would scan its full ~1-year iteration
+	* budget (527,040 passes) before throwing — seconds of synchronous CPU that
+	* stalls the event loop. Catching it here makes the failure eager and cheap,
+	* consistent with every other validation throw in the constructor.
+	*
+	* Only applies when the day-of-week field is unrestricted (`*`). Under Vixie
+	* OR semantics, a restricted day-of-week keeps the schedule satisfiable via
+	* the weekday path even when no listed day-of-month fits any listed month, so
+	* such expressions must NOT be rejected.
+	*/
+	_assertSatisfiable() {
+		if (this._isDayOfWeekRestricted) return;
+		const smallestDay = this._fields.daysOfMonth[0];
+		if (!this._fields.months.some((month) => smallestDay <= this._maxDaysInMonth(month))) throw new Error(`Impossible cron expression: "${this._expression}". No day-of-month in [${this._fields.daysOfMonth.join(", ")}] ever occurs in month(s) [${this._fields.months.join(", ")}].`);
+	}
+	/**
+	* Largest possible day number for a 1-based month, taking leap years into
+	* account so February resolves to 29 (a date that does occur, just not every
+	* year). Used by satisfiability checking, never for matching a concrete date.
+	*/
+	_maxDaysInMonth(month) {
+		if (month === 2) return 29;
+		if ([
+			4,
+			6,
+			9,
+			11
+		].includes(month)) return 30;
+		return 31;
+	}
+	/**
+	* Parse a single cron field
+	*
+	* @param field - Field value (e.g., "*", "5", "1-5", "*‍/2", "1,3,5")
+	* @param min - Minimum allowed value
+	* @param max - Maximum allowed value
+	* @returns Array of matching values
+	*/
+	_parseField(field, min, max) {
+		const values = /* @__PURE__ */ new Set();
+		const parts = field.split(",");
+		for (const part of parts) {
+			const [range, stepStr] = part.split("/");
+			const step = stepStr ? parseInt(stepStr, 10) : 1;
+			if (isNaN(step) || step < 1) throw new Error(`Invalid step value in cron field: "${field}"`);
+			let rangeStart;
+			let rangeEnd;
+			if (range === "*") {
+				rangeStart = min;
+				rangeEnd = max;
+			} else if (range.includes("-")) {
+				const [startStr, endStr] = range.split("-");
+				rangeStart = parseInt(startStr, 10);
+				rangeEnd = parseInt(endStr, 10);
+				if (isNaN(rangeStart) || isNaN(rangeEnd)) throw new Error(`Invalid range in cron field: "${field}"`);
+				if (rangeStart < min || rangeEnd > max || rangeStart > rangeEnd) throw new Error(`Range out of bounds in cron field: "${field}" (valid: ${min}-${max})`);
+			} else {
+				const value = parseInt(range, 10);
+				if (isNaN(value)) throw new Error(`Invalid value in cron field: "${field}"`);
+				if (value < min || value > max) throw new Error(`Value out of bounds in cron field: "${field}" (valid: ${min}-${max})`);
+				rangeStart = value;
+				rangeEnd = value;
+			}
+			for (let i = rangeStart; i <= rangeEnd; i += step) values.add(i);
+		}
+		return Array.from(values).sort((a, b) => a - b);
+	}
+};
+/**
+* Parse a cron expression string
+*
+* @param expression - Cron expression (5 fields)
+* @returns CronParser instance
+*/
+function parseCron(expression) {
+	return new CronParser(expression);
+}
+
+//#endregion
+//#region ../../@warlock.js/scheduler/src/job.ts
+dayjs.default.extend(dayjs_plugin_utc_js.default);
+dayjs.default.extend(dayjs_plugin_timezone_js.default);
+dayjs.default.extend(dayjs_plugin_isSameOrAfter_js.default);
+/**
+* Days of week mapping (lowercase for consistency with Day type)
+*/
+const DAYS_OF_WEEK = [
+	"sunday",
+	"monday",
+	"tuesday",
+	"wednesday",
+	"thursday",
+	"friday",
+	"saturday"
+];
+/**
+* Validate a `HH:mm` or `HH:mm:ss` string and return its parts.
+* Throws when the format is malformed or any part is out of range.
+*/
+function parseTimeString(time) {
+	if (!/^\d{1,2}:\d{2}(:\d{2})?$/.test(time)) throw new Error("Invalid time format. Use HH:mm or HH:mm:ss.");
+	const [hour, minute, second = 0] = time.split(":").map(Number);
+	if (hour < 0 || hour > 23) throw new Error(`Invalid hour in time "${time}". Must be between 0 and 23.`);
+	if (minute < 0 || minute > 59) throw new Error(`Invalid minute in time "${time}". Must be between 0 and 59.`);
+	if (second < 0 || second > 59) throw new Error(`Invalid second in time "${time}". Must be between 0 and 59.`);
+	return {
+		hour,
+		minute,
+		second
+	};
+}
+/**
+* Job class represents a scheduled task with configurable timing and execution options.
+*
+* @example
+* ```typescript
+* const job = new Job("cleanup", async () => {
+*   await cleanupOldFiles();
+* })
+*   .everyDay()
+*   .at("03:00")
+*   .inTimezone("America/New_York")
+*   .preventOverlap()
+*   .retry(3, 1000);
+* ```
+*/
+var Job = class {
+	/**
+	* Creates a new Job instance
+	*
+	* @param name - Unique identifier for the job
+	* @param callback - Function to execute when the job runs
+	*/
+	constructor(name, _callback) {
+		this.name = name;
+		this._callback = _callback;
+		this._intervals = {};
+		this._lastRun = null;
+		this._isRunning = false;
+		this._skipIfRunning = false;
+		this._retryConfig = null;
+		this._timezone = "UTC";
+		this._cronParser = null;
+		this._completionResolvers = [];
+		this.nextRun = null;
+	}
+	/**
+	* Returns true if the job is currently executing
+	*/
+	get isRunning() {
+		return this._isRunning;
+	}
+	/**
+	* Returns the last execution timestamp (success OR failure).
+	*/
+	get lastRun() {
+		return this._lastRun;
+	}
+	/**
+	* Returns the current interval configuration (readonly)
+	*/
+	get intervals() {
+		return this._intervals;
+	}
+	/**
+	* Set a custom interval for job execution
+	*
+	* @param value - Number of time units (must be > 0)
+	* @param timeType - Type of time unit
+	* @returns this for chaining
+	* @throws Error if `value` is not a positive finite number
+	*
+	* @example
+	* ```typescript
+	* job.every(5, "minute"); // Run every 5 minutes
+	* job.every(2, "hour");   // Run every 2 hours
+	* ```
+	*/
+	every(value, timeType) {
+		if (!Number.isFinite(value) || value <= 0) throw new Error(`Invalid interval value: ${value}. Must be a positive finite number.`);
+		this._intervals.every = {
+			type: timeType,
+			value
+		};
+		this._determineNextRun();
+		return this;
+	}
+	/**
+	* Run job every second (use with caution - high frequency)
+	*/
+	everySecond() {
+		return this.every(1, "second");
+	}
+	/**
+	* Run job every specified number of seconds
+	*/
+	everySeconds(seconds) {
+		return this.every(seconds, "second");
+	}
+	/**
+	* Run job every minute
+	*/
+	everyMinute() {
+		return this.every(1, "minute");
+	}
+	/**
+	* Run job every specified number of minutes
+	*/
+	everyMinutes(minutes) {
+		return this.every(minutes, "minute");
+	}
+	/**
+	* Run job every hour
+	*/
+	everyHour() {
+		return this.every(1, "hour");
+	}
+	/**
+	* Run job every specified number of hours
+	*/
+	everyHours(hours) {
+		return this.every(hours, "hour");
+	}
+	/**
+	* Run job every day at midnight
+	*/
+	everyDay() {
+		return this.every(1, "day");
+	}
+	/**
+	* Alias for everyDay()
+	*/
+	daily() {
+		return this.everyDay();
+	}
+	/**
+	* Run job twice a day (every 12 hours)
+	*/
+	twiceDaily() {
+		return this.every(12, "hour");
+	}
+	/**
+	* Run job every week
+	*/
+	everyWeek() {
+		return this.every(1, "week");
+	}
+	/**
+	* Alias for everyWeek()
+	*/
+	weekly() {
+		return this.everyWeek();
+	}
+	/**
+	* Run job every month
+	*/
+	everyMonth() {
+		return this.every(1, "month");
+	}
+	/**
+	* Alias for everyMonth()
+	*/
+	monthly() {
+		return this.everyMonth();
+	}
+	/**
+	* Run job every year
+	*/
+	everyYear() {
+		return this.every(1, "year");
+	}
+	/**
+	* Alias for everyYear()
+	*/
+	yearly() {
+		return this.everyYear();
+	}
+	/**
+	* Alias for everyMinute() - job runs continuously every minute
+	*/
+	always() {
+		return this.everyMinute();
+	}
+	/**
+	* Schedule job using a cron expression
+	*
+	* Supports standard 5-field cron syntax:
+	* ```
+	* ┌───────────── minute (0-59)
+	* │ ┌───────────── hour (0-23)
+	* │ │ ┌───────────── day of month (1-31)
+	* │ │ │ ┌───────────── month (1-12)
+	* │ │ │ │ ┌───────────── day of week (0-6, Sunday = 0)
+	* │ │ │ │ │
+	* * * * * *
+	* ```
+	*
+	* Supports:
+	* - '*' - any value
+	* - '5' - specific value
+	* - '1,3,5' - list of values
+	* - '1-5' - range of values
+	* - '*‍/5' - step values (every 5)
+	* - '1-10/2' - range with step
+	*
+	* @param expression - Standard 5-field cron expression
+	* @returns this for chaining
+	*
+	* @example
+	* ```typescript
+	* job.cron("0 9 * * 1-5");   // 9 AM weekdays
+	* job.cron("*‍/5 * * * *");   // Every 5 minutes
+	* job.cron("0 0 1 * *");     // First day of month at midnight
+	* job.cron("0 *‍/2 * * *");   // Every 2 hours
+	* ```
+	*/
+	cron(expression) {
+		this._cronParser = new CronParser(expression);
+		this._intervals = {};
+		this._determineNextRun();
+		return this;
+	}
+	/**
+	* Get the cron expression if one is set
+	*/
+	get cronExpression() {
+		return this._cronParser?.expression ?? null;
+	}
+	/**
+	* Schedule job on a specific day
+	*
+	* @param day - Day of week (string) or day of month (number 1-31)
+	* @returns this for chaining
+	*
+	* @example
+	* ```typescript
+	* job.on("monday");  // Run on Mondays
+	* job.on(15);        // Run on the 15th of each month
+	* ```
+	*/
+	on(day) {
+		if (typeof day === "number" && (day < 1 || day > 31)) throw new Error("Invalid day of the month. Must be between 1 and 31.");
+		this._intervals.day = day;
+		if (typeof day === "number") this._intervals.dayOfMonthMode = "specific";
+		this._determineNextRun();
+		return this;
+	}
+	/**
+	* Schedule job at a specific time
+	*
+	* @param time - Time in HH:mm or HH:mm:ss format
+	* @returns this for chaining
+	*
+	* @example
+	* ```typescript
+	* job.daily().at("09:00");    // Run daily at 9 AM
+	* job.weekly().at("14:30");   // Run weekly at 2:30 PM
+	* ```
+	*/
+	at(time) {
+		parseTimeString(time);
+		this._intervals.time = time;
+		this._determineNextRun();
+		return this;
+	}
+	/**
+	* Run task at the beginning of the specified time period.
+	*
+	* - `"day"`   → 00:00 every day
+	* - `"month"` → 1st of every month at 00:00
+	* - `"year"`  → January 1st at 00:00 every year
+	*
+	* @param type - Time type (day, month, year)
+	*/
+	beginOf(type) {
+		switch (type) {
+			case "day":
+				this._intervals.every = {
+					type: "day",
+					value: 1
+				};
+				break;
+			case "month":
+				this._intervals.day = 1;
+				this._intervals.dayOfMonthMode = "specific";
+				this._intervals.every = {
+					type: "month",
+					value: 1
+				};
+				break;
+			case "year":
+				this._intervals.month = 1;
+				this._intervals.day = 1;
+				this._intervals.dayOfMonthMode = "specific";
+				this._intervals.every = {
+					type: "year",
+					value: 1
+				};
+				break;
+			default: throw new Error(`Unsupported type for beginOf: ${type}`);
+		}
+		return this.at("00:00");
+	}
+	/**
+	* Run task at the end of the specified time period.
+	*
+	* - `"day"`   → 23:59 every day
+	* - `"month"` → last day of every month at 23:59 (recomputed each cycle —
+	*   correct in February vs. March)
+	* - `"year"`  → December 31st at 23:59 every year
+	*
+	* @param type - Time type (day, month, year)
+	*/
+	endOf(type) {
+		switch (type) {
+			case "day":
+				this._intervals.every = {
+					type: "day",
+					value: 1
+				};
+				break;
+			case "month":
+				this._intervals.dayOfMonthMode = "last";
+				this._intervals.every = {
+					type: "month",
+					value: 1
+				};
+				break;
+			case "year":
+				this._intervals.month = 12;
+				this._intervals.day = 31;
+				this._intervals.dayOfMonthMode = "specific";
+				this._intervals.every = {
+					type: "year",
+					value: 1
+				};
+				break;
+			default: throw new Error(`Unsupported type for endOf: ${type}`);
+		}
+		return this.at("23:59");
+	}
+	/**
+	* Set the timezone for this job's scheduling
+	*
+	* @param tz - IANA timezone string (e.g., "America/New_York", "Europe/London")
+	* @returns this for chaining
+	*
+	* @example
+	* ```typescript
+	* job.daily().at("09:00").inTimezone("America/New_York");
+	* ```
+	*/
+	inTimezone(tz) {
+		this._timezone = tz;
+		this._determineNextRun();
+		return this;
+	}
+	/**
+	* Prevent overlapping executions of this job.
+	*
+	* When enabled, if the job is already running when it's scheduled to run again,
+	* the new execution will be skipped.
+	*
+	* @param skip - Whether to skip if already running (default: true)
+	* @returns this for chaining
+	*/
+	preventOverlap(skip = true) {
+		this._skipIfRunning = skip;
+		return this;
+	}
+	/**
+	* Configure automatic retry on failure
+	*
+	* @param maxRetries - Maximum number of retry attempts (must be ≥ 0)
+	* @param delay - Delay between retries in milliseconds (must be ≥ 0)
+	* @param backoffMultiplier - Optional multiplier for exponential backoff (must be > 0)
+	* @returns this for chaining
+	*
+	* @example
+	* ```typescript
+	* job.retry(3, 1000);           // Retry 3 times with 1s delay
+	* job.retry(5, 1000, 2);        // Exponential backoff: 1s, 2s, 4s, 8s, 16s
+	* ```
+	*/
+	retry(maxRetries, delay = 1e3, backoffMultiplier) {
+		if (!Number.isFinite(maxRetries) || maxRetries < 0) throw new Error(`Invalid maxRetries: ${maxRetries}. Must be ≥ 0.`);
+		if (!Number.isFinite(delay) || delay < 0) throw new Error(`Invalid retry delay: ${delay}. Must be ≥ 0.`);
+		if (backoffMultiplier !== void 0 && (!Number.isFinite(backoffMultiplier) || backoffMultiplier <= 0)) throw new Error(`Invalid backoffMultiplier: ${backoffMultiplier}. Must be > 0.`);
+		this._retryConfig = {
+			maxRetries,
+			delay,
+			backoffMultiplier
+		};
+		return this;
+	}
+	/**
+	* Terminate the job and clear all scheduling data
+	*/
+	terminate() {
+		this._intervals = {};
+		this._cronParser = null;
+		this.nextRun = null;
+		this._lastRun = null;
+		this._isRunning = false;
+		return this;
+	}
+	/**
+	* Prepare the job by calculating the next run time
+	* Called by the scheduler when starting
+	*/
+	prepare() {
+		this._determineNextRun();
+	}
+	/**
+	* Returns true if the job's `nextRun` has arrived, regardless of whether
+	* it is currently running. Used by the scheduler to decide whether a
+	* tick is "due" before checking overlap state.
+	*/
+	isDue() {
+		return this.nextRun !== null && this._now().isSameOrAfter(this.nextRun);
+	}
+	/**
+	* Determine if the job should run now.
+	*
+	* Combines `isDue()` with the overlap-prevention rule: when
+	* `preventOverlap()` is on and the job is already running, this returns
+	* false even if the next-run time has arrived.
+	*
+	* @returns true if the job should execute
+	*/
+	shouldRun() {
+		if (this._skipIfRunning && this._isRunning) return false;
+		return this.isDue();
+	}
+	/**
+	* Execute the job once.
+	*
+	* Always advances `lastRun` and recalculates `nextRun` (success OR failure)
+	* so a permanently failing job does not re-fire on every scheduler tick.
+	*
+	* @returns Promise resolving to the job result
+	*/
+	async run() {
+		const startTime = Date.now();
+		this._isRunning = true;
+		let result;
+		let executedRetries = 0;
+		try {
+			executedRetries = (await this._executeWithRetry()).retries;
+			result = {
+				success: true,
+				duration: Date.now() - startTime,
+				retries: executedRetries
+			};
+		} catch (error) {
+			result = {
+				success: false,
+				duration: Date.now() - startTime,
+				error,
+				retries: this._retryConfig?.maxRetries ?? 0
+			};
+		} finally {
+			this._lastRun = this._now();
+			this._determineNextRun();
+			this._isRunning = false;
+			const resolvers = this._completionResolvers.splice(0);
+			for (const resolve of resolvers) resolve();
+		}
+		return result;
+	}
+	/**
+	* Wait for the currently executing run to complete.
+	*
+	* Multiple concurrent waiters are all resolved when the run finishes.
+	* Useful for graceful shutdown.
+	*
+	* @returns Promise that resolves when the job completes
+	*/
+	waitForCompletion() {
+		if (!this._isRunning) return Promise.resolve();
+		return new Promise((resolve) => {
+			this._completionResolvers.push(resolve);
+		});
+	}
+	/**
+	* Get current time, respecting the configured timezone.
+	*/
+	_now() {
+		return (0, dayjs.default)().tz(this._timezone);
+	}
+	/**
+	* Execute the callback with retry logic
+	*/
+	async _executeWithRetry() {
+		let lastError;
+		let attempts = 0;
+		const maxAttempts = (this._retryConfig?.maxRetries ?? 0) + 1;
+		while (attempts < maxAttempts) try {
+			await this._callback(this);
+			return { retries: attempts };
+		} catch (error) {
+			lastError = error;
+			attempts++;
+			if (attempts < maxAttempts && this._retryConfig) {
+				const delay = this._calculateRetryDelay(attempts);
+				await this._sleep(delay);
+			}
+		}
+		throw lastError;
+	}
+	/**
+	* Calculate retry delay with optional exponential backoff
+	*/
+	_calculateRetryDelay(attempt) {
+		if (!this._retryConfig) return 0;
+		const { delay, backoffMultiplier } = this._retryConfig;
+		if (backoffMultiplier) return delay * Math.pow(backoffMultiplier, attempt - 1);
+		return delay;
+	}
+	/**
+	* Sleep for specified milliseconds
+	*/
+	_sleep(ms) {
+		return new Promise((resolve) => setTimeout(resolve, ms));
+	}
+	/**
+	* Apply month / day-of-month / day-of-week / time constraints to a Dayjs.
+	*
+	* Re-applied after every interval advance inside `_determineNextRun` so
+	* dynamic constraints (`dayOfMonthMode: "last"` recomputed per month, month
+	* lock for `beginOf/endOf("year")`) stay correct as the candidate moves
+	* forward.
+	*/
+	_applyConstraints(date) {
+		let result = date;
+		if (this._intervals.month !== void 0) result = result.month(this._intervals.month - 1);
+		if (this._intervals.dayOfMonthMode === "last") result = result.date(result.daysInMonth());
+		else if (this._intervals.day !== void 0) if (typeof this._intervals.day === "number") result = result.date(this._intervals.day);
+		else {
+			const targetDay = DAYS_OF_WEEK.indexOf(this._intervals.day);
+			if (targetDay !== -1) result = result.day(targetDay);
+		}
+		if (this._intervals.time) {
+			const { hour, minute, second } = parseTimeString(this._intervals.time);
+			result = result.hour(hour).minute(minute).second(second).millisecond(0);
+		}
+		return result;
+	}
+	/**
+	* Calculate the next run time based on interval or cron configuration.
+	*
+	* Strategy: apply all constraints (month, day, time) ONCE before the
+	* advance loop, then advance by `every` until the candidate is in the
+	* future. Static constraints (numeric day, fixed month, fixed time)
+	* survive `dayjs.add()` automatically. The only dynamic constraint —
+	* `dayOfMonthMode: "last"` — is re-applied inside the loop so the
+	* candidate always lands on the *new* month's last day after each
+	* advance.
+	*
+	* Re-applying time/day inside the loop would deadlock: with
+	* `twiceDaily().at("06:00")` we'd advance 06:00 → 18:00 → snap back to
+	* 06:00 → 18:00 → ... forever.
+	*/
+	_determineNextRun() {
+		if (this._cronParser) {
+			const now = this._now();
+			this.nextRun = this._cronParser.nextRun(now);
+			return;
+		}
+		const intervalValue = this._intervals.every?.value;
+		const intervalType = this._intervals.every?.type;
+		const hasInterval = !!(intervalValue && intervalType);
+		let date;
+		if (this._lastRun && hasInterval) date = this._lastRun.add(intervalValue, intervalType);
+		else if (this._lastRun) date = this._lastRun.add(1, "second");
+		else date = this._now();
+		date = this._applyConstraints(date);
+		while (date.isBefore(this._now())) {
+			if (hasInterval) date = date.add(intervalValue, intervalType);
+			else date = date.add(1, "day");
+			if (this._intervals.dayOfMonthMode === "last") date = date.date(date.daysInMonth());
+		}
+		this.nextRun = date;
+	}
+};
+/**
+* Factory function to create a new Job instance
+*
+* @param name - Unique identifier for the job
+* @param callback - Function to execute when the job runs
+* @returns New Job instance
+*
+* @example
+* ```typescript
+* const cleanupJob = job("cleanup", async () => {
+*   await db.deleteExpiredTokens();
+* }).daily().at("03:00");
+* ```
+*/
+function job(name, callback) {
+	return new Job(name, callback);
+}
+
+//#endregion
+//#region ../../@warlock.js/scheduler/src/scheduler.ts
+/**
+* Scheduler class manages and executes scheduled jobs.
+*
+* Features:
+* - Event-based observability
+* - Parallel or sequential job execution
+* - Drift compensation for accurate timing
+* - Graceful shutdown with job draining
+*
+* @example
+* ```typescript
+* const scheduler = new Scheduler();
+*
+* scheduler.on('job:error', (jobName, error) => {
+*   logger.error(`Job ${jobName} failed:`, error);
+* });
+*
+* scheduler
+*   .addJob(cleanupJob)
+*   .addJob(reportJob)
+*   .runInParallel(true)
+*   .start();
+*
+* // Graceful shutdown
+* process.on('SIGTERM', () => scheduler.shutdown());
+* ```
+*/
+var Scheduler = class extends node_events.EventEmitter {
+	constructor(..._args) {
+		super(..._args);
+		this._jobs = [];
+		this._timeoutId = null;
+		this._tickInterval = 1e3;
+		this._runInParallel = false;
+		this._maxConcurrency = 10;
+		this._isShuttingDown = false;
+	}
+	/**
+	* Returns true if the scheduler is currently running
+	*/
+	get isRunning() {
+		return this._timeoutId !== null;
+	}
+	/**
+	* Returns the number of registered jobs
+	*/
+	get jobCount() {
+		return this._jobs.length;
+	}
+	/**
+	* Add a job to the scheduler
+	*
+	* @param job - Job instance to schedule
+	* @returns this for chaining
+	*/
+	addJob(job) {
+		this._jobs.push(job);
+		if (this.isRunning) job.prepare();
+		return this;
+	}
+	/**
+	* Alias to create a new job directly and store it
+	*/
+	newJob(name, jobCallback) {
+		const job = new Job(name, jobCallback);
+		this.addJob(job);
+		return job;
+	}
+	/**
+	* Add multiple jobs to the scheduler.
+	*
+	* If the scheduler is already running, every newly-added job is prepared
+	* (its initial `nextRun` is computed) so it begins firing on the next tick.
+	*
+	* @param jobs - Array of Job instances
+	* @returns this for chaining
+	*/
+	addJobs(jobs) {
+		this._jobs.push(...jobs);
+		if (this.isRunning) for (const job of jobs) job.prepare();
+		return this;
+	}
+	/**
+	* Remove a job from the scheduler by name
+	*
+	* @param jobName - Name of the job to remove
+	* @returns true if job was found and removed
+	*/
+	removeJob(jobName) {
+		const index = this._jobs.findIndex((j) => j.name === jobName);
+		if (index !== -1) {
+			this._jobs.splice(index, 1);
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Get a job by name
+	*
+	* @param jobName - Name of the job to find
+	* @returns Job instance or undefined
+	*/
+	getJob(jobName) {
+		return this._jobs.find((j) => j.name === jobName);
+	}
+	/**
+	* Get all registered jobs
+	*
+	* @returns Array of registered jobs (readonly)
+	*/
+	list() {
+		return this._jobs;
+	}
+	/**
+	* Set the tick interval (how often to check for due jobs)
+	*
+	* @param ms - Interval in milliseconds (minimum 100ms)
+	* @returns this for chaining
+	*/
+	runEvery(ms) {
+		if (ms < 100) throw new Error("Tick interval must be at least 100ms");
+		this._tickInterval = ms;
+		return this;
+	}
+	/**
+	* Configure whether jobs should run in parallel
+	*
+	* @param parallel - Enable parallel execution
+	* @param maxConcurrency - Maximum concurrent jobs (default: 10)
+	* @returns this for chaining
+	*/
+	runInParallel(parallel, maxConcurrency = 10) {
+		this._runInParallel = parallel;
+		this._maxConcurrency = maxConcurrency;
+		return this;
+	}
+	/**
+	* Start the scheduler
+	*
+	* @throws Error if scheduler is already running
+	*/
+	start() {
+		if (this.isRunning) throw new Error("Scheduler is already running.");
+		if (this._jobs.length === 0) throw new Error("Cannot start scheduler with no jobs.");
+		for (const job of this._jobs) job.prepare();
+		this._isShuttingDown = false;
+		this._scheduleTick(this._tickInterval);
+		this.emit("scheduler:started");
+	}
+	/**
+	* Stop the scheduler immediately.
+	*
+	* No-op if the scheduler isn't running. Does not wait for in-flight jobs —
+	* use `shutdown()` for graceful termination.
+	*/
+	stop() {
+		if (!this._timeoutId) return;
+		clearTimeout(this._timeoutId);
+		this._timeoutId = null;
+		this.emit("scheduler:stopped");
+	}
+	/**
+	* Gracefully shutdown the scheduler
+	*
+	* Stops scheduling new jobs and waits for currently running jobs to complete.
+	*
+	* @param timeout - Maximum time to wait for jobs (default: 30000ms)
+	* @returns Promise that resolves when shutdown is complete
+	*/
+	async shutdown(timeout = 3e4) {
+		this._isShuttingDown = true;
+		this.stop();
+		const runningJobs = this._jobs.filter((j) => j.isRunning);
+		if (runningJobs.length > 0) await Promise.race([Promise.all(runningJobs.map((j) => j.waitForCompletion())), new Promise((resolve) => setTimeout(resolve, timeout))]);
+	}
+	/**
+	* Schedule the next tick.
+	*
+	* Drift-compensated: after each tick, the next delay is `tickInterval -
+	* elapsed-tick-time` (clamped to 0). A tick that takes 600 ms on a 1 000 ms
+	* interval will be followed by a 400 ms delay so the *period* between tick
+	* starts averages `tickInterval` instead of `tickInterval + work-time`.
+	*/
+	_scheduleTick(delay) {
+		if (this._isShuttingDown) return;
+		this._timeoutId = setTimeout(async () => {
+			const tickStart = Date.now();
+			await this._tick();
+			const elapsed = Date.now() - tickStart;
+			const nextDelay = Math.max(this._tickInterval - elapsed, 0);
+			this._scheduleTick(nextDelay);
+		}, delay);
+	}
+	/**
+	* Execute a scheduler tick - check and run due jobs
+	*/
+	async _tick() {
+		this.emit("scheduler:tick", /* @__PURE__ */ new Date());
+		const dueJobs = this._jobs.filter((job) => {
+			if (!job.isDue()) return false;
+			if (job.isRunning) {
+				this.emit("job:skip", job.name, "Job is already running");
+				return false;
+			}
+			return true;
+		});
+		if (dueJobs.length === 0) return;
+		if (this._runInParallel) await this._runJobsInParallel(dueJobs);
+		else await this._runJobsSequentially(dueJobs);
+	}
+	/**
+	* Run jobs sequentially
+	*/
+	async _runJobsSequentially(jobs) {
+		for (const job of jobs) {
+			if (this._isShuttingDown) break;
+			await this._runJob(job);
+		}
+	}
+	/**
+	* Run jobs in parallel with concurrency limit
+	*/
+	async _runJobsInParallel(jobs) {
+		const batches = [];
+		for (let i = 0; i < jobs.length; i += this._maxConcurrency) batches.push(jobs.slice(i, i + this._maxConcurrency));
+		for (const batch of batches) {
+			if (this._isShuttingDown) break;
+			await Promise.allSettled(batch.map((job) => this._runJob(job)));
+		}
+	}
+	/**
+	* Run a single job and emit events
+	*/
+	async _runJob(job) {
+		this.emit("job:start", job.name);
+		const result = await job.run();
+		if (result.success) this.emit("job:complete", job.name, result);
+		else this.emit("job:error", job.name, result.error);
+		return result;
+	}
+};
+/**
+* Default scheduler instance for simple use cases
+*
+* @example
+* ```typescript
+* import { scheduler, job } from "@warlock.js/scheduler";
+*
+* scheduler.addJob(job("cleanup", cleanupFn).daily());
+* scheduler.start();
+* ```
+*/
+const scheduler = new Scheduler();
+
+//#endregion
+exports.CronParser = CronParser;
+exports.Job = Job;
+exports.Scheduler = Scheduler;
+exports.job = job;
+exports.parseCron = parseCron;
+exports.scheduler = scheduler;
+//# sourceMappingURL=index.cjs.map