@azlib/scheduler 0.2.0

package/dist/index.cjs

@@ -0,0 +1,645 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let node_crypto = require("node:crypto");
+let _azlib_cache = require("@azlib/cache");
+let _azlib_logger = require("@azlib/logger");
+//#region src/core/scheduler-host-binding.ts
+function bindSchedulerToHost(scheduler, host) {
+	host.onStart(() => scheduler.start());
+	host.onStop(() => scheduler.stop());
+}
+//#endregion
+//#region src/core/cron-expression-builder.ts
+const CronWeekday = {
+	Sunday: 0,
+	Monday: 1,
+	Tuesday: 2,
+	Wednesday: 3,
+	Thursday: 4,
+	Friday: 5,
+	Saturday: 6
+};
+function assertIntegerInRange(label, value, min, max) {
+	if (!Number.isInteger(value) || value < min || value > max) throw new Error(`${label} must be an integer between ${min} and ${max}`);
+}
+function assertPositiveInteger(label, value) {
+	if (!Number.isInteger(value) || value <= 0) throw new Error(`${label} must be a positive integer`);
+}
+function assertStepInRange(label, value, max) {
+	assertPositiveInteger(label, value);
+	if (value > max) throw new Error(`${label} must be less than or equal to ${max}`);
+}
+function toSortedCsv(values) {
+	return [...new Set(values)].sort((left, right) => left - right).join(",");
+}
+var CronExpressionBuilder = class {
+	minute = "*";
+	hour = "*";
+	dayOfMonth = "*";
+	month = "*";
+	dayOfWeek = "*";
+	everyMinute() {
+		this.minute = "*";
+		return this;
+	}
+	everyNMinutes(interval) {
+		assertStepInRange("minute interval", interval, 59);
+		this.minute = `*/${interval}`;
+		return this;
+	}
+	atMinute(minute) {
+		assertIntegerInRange("minute", minute, 0, 59);
+		this.minute = String(minute);
+		return this;
+	}
+	atMinutes(minutes) {
+		if (minutes.length === 0) throw new Error("minutes must contain at least one value");
+		minutes.forEach((minute) => assertIntegerInRange("minute", minute, 0, 59));
+		this.minute = toSortedCsv(minutes);
+		return this;
+	}
+	everyHour() {
+		this.hour = "*";
+		return this;
+	}
+	everyNHours(interval) {
+		assertStepInRange("hour interval", interval, 23);
+		this.hour = `*/${interval}`;
+		return this;
+	}
+	atHour(hour) {
+		assertIntegerInRange("hour", hour, 0, 23);
+		this.hour = String(hour);
+		return this;
+	}
+	atHours(hours) {
+		if (hours.length === 0) throw new Error("hours must contain at least one value");
+		hours.forEach((hour) => assertIntegerInRange("hour", hour, 0, 23));
+		this.hour = toSortedCsv(hours);
+		return this;
+	}
+	onDayOfMonth(day) {
+		assertIntegerInRange("day of month", day, 1, 31);
+		this.dayOfMonth = String(day);
+		return this;
+	}
+	onDaysOfMonth(days) {
+		if (days.length === 0) throw new Error("days must contain at least one value");
+		days.forEach((day) => assertIntegerInRange("day of month", day, 1, 31));
+		this.dayOfMonth = toSortedCsv(days);
+		return this;
+	}
+	everyNDaysOfMonth(interval) {
+		assertStepInRange("day-of-month interval", interval, 31);
+		this.dayOfMonth = `*/${interval}`;
+		return this;
+	}
+	everyMonth() {
+		this.month = "*";
+		return this;
+	}
+	onMonth(month) {
+		assertIntegerInRange("month", month, 1, 12);
+		this.month = String(month);
+		return this;
+	}
+	onMonths(months) {
+		if (months.length === 0) throw new Error("months must contain at least one value");
+		months.forEach((month) => assertIntegerInRange("month", month, 1, 12));
+		this.month = toSortedCsv(months);
+		return this;
+	}
+	everyNMonths(interval) {
+		assertStepInRange("month interval", interval, 12);
+		this.month = `*/${interval}`;
+		return this;
+	}
+	onWeekday(weekday) {
+		assertIntegerInRange("weekday", weekday, 0, 6);
+		this.dayOfWeek = String(weekday);
+		return this;
+	}
+	onWeekdays(weekdays) {
+		if (weekdays.length === 0) throw new Error("weekdays must contain at least one value");
+		weekdays.forEach((weekday) => assertIntegerInRange("weekday", weekday, 0, 6));
+		this.dayOfWeek = toSortedCsv(weekdays);
+		return this;
+	}
+	everyNWeekdays(interval) {
+		assertStepInRange("weekday interval", interval, 6);
+		this.dayOfWeek = `*/${interval}`;
+		return this;
+	}
+	weekdays() {
+		this.dayOfWeek = "1-5";
+		return this;
+	}
+	weekends() {
+		this.dayOfWeek = "0,6";
+		return this;
+	}
+	dailyAt(hour, minute = 0) {
+		this.atHour(hour);
+		this.atMinute(minute);
+		this.dayOfMonth = "*";
+		this.month = "*";
+		this.dayOfWeek = "*";
+		return this;
+	}
+	weeklyOn(weekday, hour = 0, minute = 0) {
+		this.atHour(hour);
+		this.atMinute(minute);
+		this.dayOfWeek = String(weekday);
+		this.dayOfMonth = "*";
+		this.month = "*";
+		return this;
+	}
+	monthlyOn(dayOfMonth, hour = 0, minute = 0) {
+		this.atHour(hour);
+		this.atMinute(minute);
+		this.onDayOfMonth(dayOfMonth);
+		this.month = "*";
+		this.dayOfWeek = "*";
+		return this;
+	}
+	build() {
+		return `${this.minute} ${this.hour} ${this.dayOfMonth} ${this.month} ${this.dayOfWeek}`;
+	}
+	toString() {
+		return this.build();
+	}
+};
+function createCronExpression() {
+	return new CronExpressionBuilder();
+}
+//#endregion
+//#region src/core/job-execution-store.ts
+function createInMemoryJobExecutionStore() {
+	const byExecution = /* @__PURE__ */ new Map();
+	return {
+		create(record) {
+			byExecution.set(record.executionId, record);
+			return record;
+		},
+		update(executionId, patch) {
+			const current = byExecution.get(executionId);
+			if (!current) return null;
+			const next = {
+				...current,
+				...patch
+			};
+			byExecution.set(executionId, next);
+			return next;
+		},
+		listByJob(jobId) {
+			return Array.from(byExecution.values()).filter((item) => item.jobId === jobId);
+		}
+	};
+}
+//#endregion
+//#region src/core/schedule-cursor-store.ts
+function createInMemoryScheduleCursorStore() {
+	const cursors = /* @__PURE__ */ new Map();
+	return {
+		set(jobId, nextRunAt, now) {
+			const previous = cursors.get(jobId);
+			const next = {
+				jobId,
+				lastEvaluatedAt: now,
+				lastTriggeredAt: previous?.lastTriggeredAt,
+				nextRunAt,
+				version: (previous?.version ?? 0) + 1
+			};
+			cursors.set(jobId, next);
+			return next;
+		},
+		markTriggered(jobId, triggeredAt) {
+			const current = cursors.get(jobId);
+			if (!current) return null;
+			const next = {
+				...current,
+				lastTriggeredAt: triggeredAt,
+				version: current.version + 1
+			};
+			cursors.set(jobId, next);
+			return next;
+		},
+		get(jobId) {
+			return cursors.get(jobId) ?? null;
+		},
+		remove(jobId) {
+			return cursors.delete(jobId);
+		}
+	};
+}
+//#endregion
+//#region src/core/scheduler-cache.ts
+function createSchedulerCache(namespace = "scheduler-core") {
+	return (0, _azlib_cache.createCache)({
+		mode: "memory",
+		namespace
+	});
+}
+//#endregion
+//#region src/core/schedule-parser.ts
+const CRON_FIELD_PATTERN = /^\*|\*\/\d+|\d+|\d+-\d+|\d+(?:,\d+)*$/;
+function assertValidTimezone(timezone) {
+	try {
+		new Intl.DateTimeFormat("en-US", { timeZone: timezone }).format(/* @__PURE__ */ new Date());
+	} catch {
+		throw new Error(`Invalid timezone: ${timezone}`);
+	}
+}
+function assertValidCronExpression(expression) {
+	const fields = expression.trim().split(/\s+/);
+	if (fields.length !== 5) throw new Error("Cron expression must contain 5 fields");
+	for (const field of fields) if (!CRON_FIELD_PATTERN.test(field)) throw new Error(`Invalid cron field: ${field}`);
+}
+function assertValidOnceExpression(expression) {
+	const date = new Date(expression);
+	if (Number.isNaN(date.getTime())) throw new Error("Once schedule expression must be a valid ISO datetime");
+}
+function parseSchedule(scheduleType, expression, timezone) {
+	assertValidTimezone(timezone);
+	if (scheduleType === "cron") assertValidCronExpression(expression);
+	else assertValidOnceExpression(expression);
+	return {
+		scheduleType,
+		expression: expression.trim(),
+		timezone
+	};
+}
+function computeNextRunAt(parsed, now = /* @__PURE__ */ new Date()) {
+	if (parsed.scheduleType === "once") return new Date(parsed.expression).toISOString();
+	const next = new Date(now);
+	next.setUTCSeconds(0, 0);
+	next.setUTCMinutes(next.getUTCMinutes() + 1);
+	return next.toISOString();
+}
+//#endregion
+//#region src/core/scheduler-engine.ts
+function createSchedulerEngine(dependencies) {
+	let timer;
+	async function computeNextRun(job, now = /* @__PURE__ */ new Date()) {
+		const cacheKey = `scheduler.nextRun.${job.jobId}.${job.schedule.expression}.${job.schedule.timezone}`;
+		const cached = await dependencies.cache?.get(cacheKey);
+		if (cached?.status === "hit" && cached.value) return cached.value;
+		const nextRunAt = computeNextRunAt(parseSchedule(job.schedule.scheduleType, job.schedule.expression, job.schedule.timezone), now);
+		await dependencies.cache?.set(cacheKey, nextRunAt);
+		dependencies.cursorStore.set(job.jobId, nextRunAt, now.toISOString());
+		return nextRunAt;
+	}
+	async function evaluateTick() {
+		const now = /* @__PURE__ */ new Date();
+		const candidates = dependencies.jobStore.list().filter((job) => job.enabled).slice(0, dependencies.maxDueJobsPerTick);
+		for (const job of candidates) {
+			const nextRunAt = await computeNextRun(job, now);
+			if (new Date(nextRunAt).getTime() > now.getTime()) continue;
+			const executionId = `exec_${(0, node_crypto.randomUUID)()}`;
+			dependencies.executionStore.create({
+				executionId,
+				jobId: job.jobId,
+				scheduledFor: nextRunAt,
+				triggeredAt: now.toISOString(),
+				status: "queued",
+				attemptCount: 0
+			});
+			dependencies.cursorStore.markTriggered(job.jobId, now.toISOString());
+			if (dependencies.queueService) await dependencies.queueService.enqueue({
+				idempotencyKey: `scheduler:${job.jobId}:${nextRunAt}`,
+				payloadRef: {
+					executionId,
+					handlerKey: job.handlerKey,
+					config: job.config
+				}
+			});
+			dependencies.logger.info("scheduler.job.triggered", {
+				executionId,
+				jobId: job.jobId,
+				scheduledFor: nextRunAt
+			});
+		}
+	}
+	return {
+		async start() {
+			if (timer) return;
+			dependencies.logger.info("scheduler.runtime.started", { tickIntervalMs: dependencies.tickIntervalMs });
+			timer = setInterval(() => {
+				evaluateTick().catch((error) => {
+					dependencies.logger.error("scheduler.tick.failed", { error: error instanceof Error ? error.message : "Unknown scheduler error" });
+				});
+			}, dependencies.tickIntervalMs);
+		},
+		async stop() {
+			if (!timer) return;
+			clearInterval(timer);
+			timer = void 0;
+			dependencies.logger.info("scheduler.runtime.stopped");
+		},
+		computeNextRun
+	};
+}
+//#endregion
+//#region src/core/scheduler-events.ts
+function createInMemorySchedulerEventBus() {
+	const events = [];
+	return {
+		emit(event) {
+			const record = {
+				eventId: `evt_${Math.random().toString(36).slice(2, 12)}`,
+				timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+				...event
+			};
+			events.push(record);
+			return record;
+		},
+		list() {
+			return [...events];
+		}
+	};
+}
+//#endregion
+//#region src/core/scheduler-handler-registry.ts
+function createSchedulerHandlerRegistry() {
+	const handlers = /* @__PURE__ */ new Map();
+	return {
+		register(handlerKey, handler) {
+			handlers.set(handlerKey, handler);
+		},
+		resolve(handlerKey) {
+			return handlers.get(handlerKey) ?? null;
+		},
+		has(handlerKey) {
+			return handlers.has(handlerKey);
+		}
+	};
+}
+//#endregion
+//#region src/core/scheduler-job-store.ts
+function createInMemorySchedulerJobStore() {
+	const jobs = /* @__PURE__ */ new Map();
+	return {
+		create(jobId, definition) {
+			const now = (/* @__PURE__ */ new Date()).toISOString();
+			const created = {
+				...definition,
+				jobId,
+				enabled: definition.enabled ?? true,
+				createdAt: now,
+				updatedAt: now
+			};
+			jobs.set(jobId, created);
+			return created;
+		},
+		update(jobId, patch) {
+			const current = jobs.get(jobId);
+			if (!current) return null;
+			const updated = {
+				...current,
+				...patch,
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			jobs.set(jobId, updated);
+			return updated;
+		},
+		setEnabled(jobId, enabled) {
+			const current = jobs.get(jobId);
+			if (!current) return null;
+			const updated = {
+				...current,
+				enabled,
+				updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+			};
+			jobs.set(jobId, updated);
+			return updated;
+		},
+		get(jobId) {
+			return jobs.get(jobId) ?? null;
+		},
+		list() {
+			return Array.from(jobs.values());
+		},
+		remove(jobId) {
+			return jobs.delete(jobId);
+		}
+	};
+}
+//#endregion
+//#region src/core/scheduler-logger.ts
+function createSchedulerLogger() {
+	return (0, _azlib_logger.createLogger)({
+		level: "info",
+		transports: [(0, _azlib_logger.createConsoleTransport)()]
+	});
+}
+//#endregion
+//#region src/core/scheduler-runtime.ts
+function createSchedulerRuntime(engine) {
+	let started = false;
+	return {
+		async start() {
+			if (started) return;
+			started = true;
+			await engine.start();
+		},
+		async stop() {
+			if (!started) return;
+			started = false;
+			await engine.stop();
+		}
+	};
+}
+//#endregion
+//#region src/core/scheduler-runtime-config.ts
+function assertRuntimeConfig(options) {
+	if (options.tickIntervalMs !== void 0 && options.tickIntervalMs <= 0) throw new Error("tickIntervalMs must be greater than 0");
+	if (options.maxDueJobsPerTick !== void 0 && options.maxDueJobsPerTick < 1) throw new Error("maxDueJobsPerTick must be at least 1");
+}
+//#endregion
+//#region src/core/scheduler-service-query.ts
+function toJobListItem(input) {
+	return {
+		jobId: input.jobId,
+		name: input.name,
+		enabled: input.enabled,
+		timezone: input.timezone,
+		nextRunAt: input.nextRunAt
+	};
+}
+function filterExecutions(items, query) {
+	if (!query) return items;
+	const fromTime = query.from ? new Date(query.from).getTime() : void 0;
+	const toTime = query.to ? new Date(query.to).getTime() : void 0;
+	return items.filter((item) => query.jobId ? item.jobId === query.jobId : true).filter((item) => query.status ? item.status === query.status : true).filter((item) => {
+		if (fromTime === void 0) return true;
+		return new Date(item.triggeredAt).getTime() >= fromTime;
+	}).filter((item) => {
+		if (toTime === void 0) return true;
+		return new Date(item.triggeredAt).getTime() <= toTime;
+	}).slice(0, query.limit ?? items.length);
+}
+//#endregion
+//#region src/core/scheduler-service-retry.ts
+function retryFailedExecutionById(allExecutions, executionStore, executionId) {
+	const target = allExecutions.find((item) => item.executionId === executionId);
+	if (!target) throw new Error(`Execution not found: ${executionId}`);
+	if (target.status !== "failed" && target.status !== "dead-letter") throw new Error("Only failed or dead-letter executions can be retried");
+	const retryExecutionId = `exec_${(0, node_crypto.randomUUID)()}`;
+	const retry = {
+		...target,
+		executionId: retryExecutionId,
+		status: "queued",
+		attemptCount: target.attemptCount + 1,
+		triggeredAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	executionStore.create(retry);
+	return retry;
+}
+//#endregion
+//#region src/core/scheduler-service.ts
+function createSchedulerService$1(options) {
+	assertRuntimeConfig(options);
+	const logger = options.logger ?? createSchedulerLogger();
+	const cache = options.cache ?? createSchedulerCache();
+	const jobStore = createInMemorySchedulerJobStore();
+	const cursorStore = createInMemoryScheduleCursorStore();
+	const executionStore = createInMemoryJobExecutionStore();
+	const events = createInMemorySchedulerEventBus();
+	const handlers = createSchedulerHandlerRegistry();
+	const queueService = options.queueService;
+	const engine = createSchedulerEngine({
+		queueService,
+		cache,
+		logger,
+		jobStore,
+		cursorStore,
+		executionStore,
+		tickIntervalMs: options.tickIntervalMs ?? 1e3,
+		maxDueJobsPerTick: options.maxDueJobsPerTick ?? 200
+	});
+	const runtime = createSchedulerRuntime(engine);
+	return {
+		service: {
+			async registerJob(job) {
+				if (!handlers.has(job.handlerKey)) throw new Error(`Unknown handlerKey: ${job.handlerKey}`);
+				const jobId = `job_${(0, node_crypto.randomUUID)()}`;
+				const created = jobStore.create(jobId, job);
+				const nextRunAt = await engine.computeNextRun(created);
+				cursorStore.set(jobId, nextRunAt, (/* @__PURE__ */ new Date()).toISOString());
+				events.emit({
+					eventType: "job-created",
+					jobId,
+					metadata: { name: job.name }
+				});
+				return { jobId };
+			},
+			async updateJob(jobId, patch) {
+				const updated = jobStore.update(jobId, patch);
+				if (!updated) throw new Error(`Job not found: ${jobId}`);
+				const nextRunAt = await engine.computeNextRun(updated);
+				cursorStore.set(jobId, nextRunAt, (/* @__PURE__ */ new Date()).toISOString());
+				events.emit({
+					eventType: "job-updated",
+					jobId
+				});
+			},
+			async pauseJob(jobId) {
+				if (!jobStore.setEnabled(jobId, false)) throw new Error(`Job not found: ${jobId}`);
+				events.emit({
+					eventType: "job-paused",
+					jobId
+				});
+			},
+			async resumeJob(jobId) {
+				if (!jobStore.setEnabled(jobId, true)) throw new Error(`Job not found: ${jobId}`);
+				events.emit({
+					eventType: "job-resumed",
+					jobId
+				});
+			},
+			async deleteJob(jobId) {
+				const removed = jobStore.remove(jobId);
+				cursorStore.remove(jobId);
+				if (!removed) throw new Error(`Job not found: ${jobId}`);
+				events.emit({
+					eventType: "job-deleted",
+					jobId
+				});
+			},
+			async listJobs() {
+				return jobStore.list().map((job) => {
+					const cursor = cursorStore.get(job.jobId);
+					return toJobListItem({
+						jobId: job.jobId,
+						name: job.name,
+						enabled: job.enabled,
+						timezone: job.schedule.timezone,
+						nextRunAt: cursor?.nextRunAt
+					});
+				});
+			},
+			async listExecutions(query) {
+				return filterExecutions(jobStore.list().flatMap((job) => executionStore.listByJob(job.jobId)), query);
+			},
+			async retryFailedExecution(executionId) {
+				const retry = retryFailedExecutionById(jobStore.list().flatMap((job) => executionStore.listByJob(job.jobId)), executionStore, executionId);
+				events.emit({
+					eventType: "retry",
+					jobId: retry.jobId,
+					executionId: retry.executionId,
+					metadata: { previousExecutionId: executionId }
+				});
+			},
+			async start() {
+				logger.info("scheduler.service.start", { mode: options.mode });
+				await runtime.start();
+			},
+			async stop() {
+				logger.info("scheduler.service.stop", { mode: options.mode });
+				await runtime.stop();
+			}
+		},
+		handlers
+	};
+}
+//#endregion
+//#region src/dashboard/queue-queries.ts
+async function querySchedulerHealth(scheduler) {
+	const jobs = await scheduler.listJobs();
+	const executions = await scheduler.listExecutions({ status: "failed" });
+	return {
+		totalJobs: jobs.length,
+		enabledJobs: jobs.filter((job) => job.enabled).length,
+		pausedJobs: jobs.filter((job) => !job.enabled).length,
+		failedExecutions: executions.length
+	};
+}
+async function querySchedulerItems(scheduler) {
+	const jobs = await scheduler.listJobs();
+	const executions = await scheduler.listExecutions({ limit: 100 });
+	return jobs.map((job) => ({
+		...job,
+		executions: executions.filter((execution) => execution.jobId === job.jobId)
+	}));
+}
+//#endregion
+//#region src/dashboard/queue-dashboard-service.ts
+function createSchedulerDashboardService(scheduler) {
+	return {
+		getHealth: () => querySchedulerHealth(scheduler),
+		listItems: () => querySchedulerItems(scheduler),
+		pauseJob: (jobId) => scheduler.pauseJob(jobId),
+		resumeJob: (jobId) => scheduler.resumeJob(jobId),
+		retryExecution: (executionId) => scheduler.retryFailedExecution(executionId)
+	};
+}
+//#endregion
+//#region index.ts
+function createSchedulerService(options) {
+	return createSchedulerService$1(options);
+}
+//#endregion
+exports.CronWeekday = CronWeekday;
+exports.bindSchedulerToHost = bindSchedulerToHost;
+exports.createCronExpression = createCronExpression;
+exports.createSchedulerDashboardService = createSchedulerDashboardService;
+exports.createSchedulerService = createSchedulerService;