@legonode/cron 0.0.1

package/README.md

@@ -0,0 +1,96 @@
+# @legonode/cron
+
+Cron schedules and plugin for `legonode`.
+
+This package provides:
+- A `createCronPlugin()` plugin that runs tasks from `app/cron/*.cron.ts`
+- Manual task triggering via `ctx.schedule(name, payload, options?)`
+- Schedule loader/runner utilities if you want low-level control
+
+## Install
+
+In this monorepo it is a workspace package.
+
+For external usage:
+
+```bash
+bun add @legonode/cron
+```
+
+`legonode` is a peer dependency.
+
+## Basic Usage
+
+Add the plugin in `legonode.config.ts`:
+
+```ts
+import type { LegonodeConfig } from "legonode";
+import { createCronPlugin } from "@legonode/cron";
+
+const config: LegonodeConfig = {
+  plugins: [createCronPlugin()]
+};
+
+export default config;
+```
+
+## Disable Cron In Dev
+
+If you want cron files to not run during `legonode dev`:
+
+```ts
+plugins: [createCronPlugin({ disableDevCron: true })]
+```
+
+This only disables scheduled/background runs in dev mode. The plugin still keeps cron lookup available for manual `ctx.schedule(...)`.
+
+## Cron File Format
+
+Create files in `app/cron` with names ending in `.cron.ts` (or `.js`, `.mts`, `.mjs`).
+
+Example:
+
+```ts
+import type { ScheduleDef, TaskContext } from "@legonode/cron";
+
+export const schedule: ScheduleDef = { every: "10s" };
+
+export async function run(ctx: TaskContext) {
+  console.log("cron run", ctx.payload);
+}
+```
+
+Supported schedule styles:
+- `{ every: "minute" }`
+- `{ every: "hour" }`
+- `{ every: "day", at: "09:30" }`
+- `{ every: "week", day: "monday", at: "10:00" }`
+- `{ every: "month", date: 1, at: "00:00" }`
+- `{ every: "10s" }`, `{ every: "5m" }`, `{ every: "2h" }`, etc.
+
+## Manual Trigger From Request Context
+
+The plugin augments `LegonodeContext` with:
+
+```ts
+ctx.schedule(name, payload?, { delayMs?, at? })
+```
+
+Example:
+
+```ts
+await ctx.schedule("interval.example", { source: "api" }, { delayMs: 2000 });
+```
+
+`at` accepts:
+- `Date`
+- epoch milliseconds (`number`)
+- Date-parsable string
+
+## Exports
+
+Top-level exports include:
+- `createCronPlugin`
+- `ScheduleDef`, `Schedule`, `TaskContext`, `TaskRunFn`, `LoadedTask`
+- `loadSchedulesFromApp`, `scanScheduleFiles`, `createScheduleRunner`, `runScheduler`, and related helpers
+

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { ScheduleDef, Schedule, TaskContext, TaskRunFn, LoadedTask } from "./types.js";
+export type { ScheduleRunnerFn, ScannedSchedule } from "./scheduleLoader.js";
+export { loadSchedulesFromApp, scanScheduleFiles, loadScheduleModule, createScheduleRunner, getOrCreateScheduleRunner, clearScheduleRunnerCache } from "./scheduleLoader.js";
+export { runScheduler } from "./runScheduler.js";
+export type { RunSchedulerOptions } from "./runScheduler.js";
+export { getIntervalMs, isAtSchedule, getNextRunMs } from "./parseSchedule.js";
+export { createCronPlugin } from "./plugin.js";
+export type { CronPluginOptions, ScheduleWhenOptions, ScheduleInvokeFn } from "./plugin.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { loadSchedulesFromApp, scanScheduleFiles, loadScheduleModule, createScheduleRunner, getOrCreateScheduleRunner, clearScheduleRunnerCache } from "./scheduleLoader.js";
+export { runScheduler } from "./runScheduler.js";
+export { getIntervalMs, isAtSchedule, getNextRunMs } from "./parseSchedule.js";
+export { createCronPlugin } from "./plugin.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,wBAAwB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/moduleCache.d.ts

@@ -0,0 +1,3 @@
+/** Invalidate Node/Bun module cache for a file so the next import() loads fresh (dev hot reload). */
+export declare function invalidateModuleCache(filePath: string): void;
+//# sourceMappingURL=moduleCache.d.ts.map

package/dist/moduleCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleCache.d.ts","sourceRoot":"","sources":["../src/moduleCache.ts"],"names":[],"mappings":"AAMA,qGAAqG;AACrG,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAS5D"}

package/dist/moduleCache.js

@@ -0,0 +1,19 @@
+import { createRequire } from "node:module";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+const _require = createRequire(import.meta.url);
+/** Invalidate Node/Bun module cache for a file so the next import() loads fresh (dev hot reload). */
+export function invalidateModuleCache(filePath) {
+    if (!_require.cache)
+        return;
+    const url = pathToFileURL(filePath).href;
+    const resolved = resolve(filePath);
+    const keys = new Set([url, resolved]);
+    for (const key of Object.keys(_require.cache)) {
+        if (key === resolved || key.endsWith(filePath) || key.endsWith(resolved))
+            keys.add(key);
+    }
+    for (const k of keys)
+        delete _require.cache[k];
+}
+//# sourceMappingURL=moduleCache.js.map

package/dist/moduleCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moduleCache.js","sourceRoot":"","sources":["../src/moduleCache.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAEhD,qGAAqG;AACrG,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,IAAI,CAAC,QAAQ,CAAC,KAAK;QAAE,OAAO;IAC5B,MAAM,GAAG,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC;IACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC;IAC9C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9C,IAAI,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC1F,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACjD,CAAC"}

package/dist/parseSchedule.d.ts

@@ -0,0 +1,15 @@
+import type { ScheduleDef } from "./types.js";
+/**
+ * Returns interval in ms for setInterval, or null if this is an "at" schedule (day/week/month).
+ */
+export declare function getIntervalMs(def: ScheduleDef): number | null;
+/**
+ * Returns true if this schedule runs at a specific time (day at, week day at, month date at).
+ */
+export declare function isAtSchedule(def: ScheduleDef): boolean;
+/**
+ * Get ms until the next run for "at" schedules (day at HH:MM, week day at HH:MM, month date at HH:MM).
+ * Never returns 0 so we avoid setTimeout(..., 0) and immediate re-runs.
+ */
+export declare function getNextRunMs(def: ScheduleDef): number;
+//# sourceMappingURL=parseSchedule.d.ts.map

package/dist/parseSchedule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseSchedule.d.ts","sourceRoot":"","sources":["../src/parseSchedule.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AA0C9C;;GAEG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAM7D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAKtD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,WAAW,GAAG,MAAM,CAkCrD"}

package/dist/parseSchedule.js

@@ -0,0 +1,111 @@
+const DAY_MS = 24 * 60 * 60 * 1000;
+const HOUR_MS = 60 * 60 * 1000;
+const MINUTE_MS = 60 * 1000;
+const WEEKDAYS = {
+    sunday: 0,
+    monday: 1,
+    tuesday: 2,
+    wednesday: 3,
+    thursday: 4,
+    friday: 5,
+    saturday: 6
+};
+function parseTime(at) {
+    const match = /^(\d{1,2}):(\d{2})$/.exec(at.trim());
+    if (!match)
+        return { hours: 0, minutes: 0 };
+    return {
+        hours: Math.min(23, Math.max(0, parseInt(match[1], 10))),
+        minutes: Math.min(59, Math.max(0, parseInt(match[2], 10)))
+    };
+}
+/** Parse interval string like "5m", "10s", "1h" to ms. */
+function parseIntervalEvery(every) {
+    const s = every.trim().toLowerCase();
+    const match = /^(\d+)\s*(s|sec|m|min|h|hr|d|day)s?$/.exec(s);
+    if (match) {
+        const n = parseInt(match[1], 10);
+        const unit = match[2];
+        if (unit === "s" || unit === "sec")
+            return n * 1000;
+        if (unit === "m" || unit === "min")
+            return n * MINUTE_MS;
+        if (unit === "h" || unit === "hr")
+            return n * HOUR_MS;
+        if (unit === "d" || unit === "day")
+            return n * DAY_MS;
+    }
+    if (s === "minute" || s === "1m")
+        return MINUTE_MS;
+    if (s === "hour" || s === "1h")
+        return HOUR_MS;
+    return null;
+}
+/**
+ * Returns interval in ms for setInterval, or null if this is an "at" schedule (day/week/month).
+ */
+export function getIntervalMs(def) {
+    if (def.every === "minute")
+        return MINUTE_MS;
+    if (def.every === "hour")
+        return HOUR_MS;
+    const interval = parseIntervalEvery(def.every);
+    if (interval !== null)
+        return interval;
+    return null;
+}
+/**
+ * Returns true if this schedule runs at a specific time (day at, week day at, month date at).
+ */
+export function isAtSchedule(def) {
+    if (def.every === "day" && "at" in def)
+        return true;
+    if (def.every === "week")
+        return true;
+    if (def.every === "month")
+        return true;
+    return false;
+}
+/**
+ * Get ms until the next run for "at" schedules (day at HH:MM, week day at HH:MM, month date at HH:MM).
+ * Never returns 0 so we avoid setTimeout(..., 0) and immediate re-runs.
+ */
+export function getNextRunMs(def) {
+    const now = new Date();
+    const at = "at" in def && typeof def.at === "string" ? def.at : "00:00";
+    const { hours, minutes } = parseTime(at);
+    let ms;
+    if (def.every === "day") {
+        let next = new Date(now);
+        next.setHours(hours, minutes, 0, 0);
+        if (next.getTime() <= now.getTime())
+            next = new Date(next.getTime() + DAY_MS);
+        ms = next.getTime() - now.getTime();
+    }
+    else if (def.every === "week") {
+        const dayName = def.day ?? "monday";
+        const targetDay = WEEKDAYS[dayName.toLowerCase()] ?? 1;
+        let next = new Date(now);
+        next.setHours(hours, minutes, 0, 0);
+        let diff = targetDay - next.getDay();
+        if (diff < 0)
+            diff += 7;
+        else if (diff === 0 && next.getTime() <= now.getTime())
+            diff = 7;
+        next = new Date(next.getTime() + diff * DAY_MS);
+        ms = next.getTime() - now.getTime();
+    }
+    else if (def.every === "month") {
+        const date = def.date ?? 1;
+        let next = new Date(now.getFullYear(), now.getMonth(), date, hours, minutes, 0, 0);
+        if (next.getTime() <= now.getTime()) {
+            next = new Date(now.getFullYear(), now.getMonth() + 1, date, hours, minutes, 0, 0);
+        }
+        ms = next.getTime() - now.getTime();
+    }
+    else {
+        ms = DAY_MS;
+    }
+    return Math.max(1, ms);
+}
+//# sourceMappingURL=parseSchedule.js.map

package/dist/parseSchedule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseSchedule.js","sourceRoot":"","sources":["../src/parseSchedule.ts"],"names":[],"mappings":"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"}

package/dist/plugin.d.ts

@@ -0,0 +1,19 @@
+import type { LegonodePlugin } from "legonode";
+export type CronPluginOptions = {
+    /** Disable scheduler in `disableDevCron` command (default: false). */
+    disableDevCron?: boolean;
+};
+export type ScheduleWhenOptions = {
+    /** Run at an absolute time (Date, epoch ms, or Date-parsable string). */
+    at?: Date | number | string;
+    /** Run after this delay (ms). */
+    delayMs?: number;
+};
+export type ScheduleInvokeFn = (name: string, payload?: unknown, options?: ScheduleWhenOptions) => void | Promise<void>;
+declare module "legonode" {
+    interface LegonodeContext {
+        schedule: ScheduleInvokeFn;
+    }
+}
+export declare function createCronPlugin(options?: CronPluginOptions): LegonodePlugin;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAS/C,MAAM,MAAM,iBAAiB,GAAG;IAC9B,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,yEAAyE;IACzE,EAAE,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;IAC5B,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,OAAO,EACjB,OAAO,CAAC,EAAE,mBAAmB,KAC1B,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAE1B,OAAO,QAAQ,UAAU,CAAC;IACxB,UAAU,eAAe;QACvB,QAAQ,EAAE,gBAAgB,CAAC;KAC5B;CACF;AAsBD,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CAmGhF"}

package/dist/plugin.js

@@ -0,0 +1,120 @@
+import { clearScheduleRunnerCache, getOrCreateScheduleRunner, loadSchedulesFromApp, } from "./scheduleLoader.js";
+import { runScheduler } from "./runScheduler.js";
+function parseAtMs(at) {
+    if (typeof at === "number")
+        return Number.isFinite(at) ? at : null;
+    if (at instanceof Date) {
+        const ms = at.getTime();
+        return Number.isFinite(ms) ? ms : null;
+    }
+    if (typeof at === "string") {
+        const ms = Date.parse(at);
+        return Number.isFinite(ms) ? ms : null;
+    }
+    return null;
+}
+function isCronFile(filename) {
+    if (!filename)
+        return false;
+    const normalized = filename.replaceAll("\\", "/");
+    // Bun/Node watch commonly reports paths like "src/cron/x.cron.ts", not "cron/x.cron.ts".
+    return normalized.includes("/cron/") && /\.cron\.(ts|js|mts|mjs)$/i.test(normalized);
+}
+export function createCronPlugin(options = {}) {
+    const disableDevCron = options.disableDevCron === true;
+    let stopScheduler = null;
+    let currentAppDir = "";
+    function attachSchedule(ctx) {
+        ctx.schedule = async (name, payload, when) => {
+            const appDir = currentAppDir;
+            if (!appDir)
+                return;
+            const runner = await getOrCreateScheduleRunner(appDir);
+            const delayMs = typeof when?.delayMs === "number" && Number.isFinite(when.delayMs)
+                ? Math.max(0, when.delayMs)
+                : null;
+            const atMs = when?.at !== undefined ? parseAtMs(when.at) : null;
+            if (delayMs === null && atMs === null) {
+                await runner(name, payload);
+                return;
+            }
+            const computedDelay = delayMs !== null ? delayMs : Math.max(0, (atMs ?? Date.now()) - Date.now());
+            if (computedDelay <= 0) {
+                await runner(name, payload);
+                return;
+            }
+            setTimeout(() => {
+                void runner(name, payload);
+            }, computedDelay);
+        };
+    }
+    async function startScheduler(appDir, cacheBust = false) {
+        if (!appDir)
+            return;
+        if (cacheBust) {
+            process.env.LEGONODE_CRON_RELOAD_TOKEN = String(Date.now());
+            clearScheduleRunnerCache(appDir);
+        }
+        stopScheduler?.();
+        stopScheduler = null;
+        currentAppDir = appDir;
+        const tasks = await loadSchedulesFromApp(appDir, process.env.LEGONODE_CRON_RELOAD_TOKEN);
+        if (tasks.length === 0)
+            return;
+        stopScheduler = runScheduler(tasks, {
+            onError: (name, error) => {
+                console.error(`[legonode cron ${name}]`, error);
+            }
+        });
+    }
+    function stopCurrent() {
+        stopScheduler?.();
+        stopScheduler = null;
+        if (currentAppDir)
+            clearScheduleRunnerCache(currentAppDir);
+    }
+    return {
+        name: "@legonode/cron",
+        onRequest(ctx) {
+            attachSchedule(ctx);
+        },
+        async onDevStart(ctx) {
+            // Keep appDir for manual ctx.schedule(...) even when dev scheduler is disabled.
+            if (ctx.appDir)
+                currentAppDir = ctx.appDir;
+            if (disableDevCron)
+                return;
+            await startScheduler(ctx.appDir);
+        },
+        async onDevFileChange(ctx) {
+            const changed = ctx.changedPath ?? ctx.filename;
+            if (!isCronFile(changed))
+                return;
+            // Manual schedule() uses the cached runner too; bust it on cron file changes.
+            if (ctx.appDir) {
+                currentAppDir = ctx.appDir;
+                process.env.LEGONODE_CRON_RELOAD_TOKEN = String(Date.now());
+                clearScheduleRunnerCache(ctx.appDir);
+            }
+            if (disableDevCron)
+                return;
+            await startScheduler(ctx.appDir, true);
+        },
+        onDevRestart() {
+            stopCurrent();
+        },
+        onDevStop() {
+            stopCurrent();
+        },
+        async onStartListening(ctx) {
+            await startScheduler(ctx.appDir);
+        },
+        onStartStop() {
+            stopCurrent();
+        },
+        onStartError() {
+            stopCurrent();
+        }
+    };
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"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"}

package/dist/runScheduler.d.ts

@@ -0,0 +1,14 @@
+import type { LoadedTask, TaskContext } from "./types.js";
+export type RunSchedulerOptions = {
+    ctx?: TaskContext;
+    onRun?: (taskName: string, ctx: TaskContext) => void | Promise<void>;
+    onComplete?: (taskName: string, ctx: TaskContext) => void | Promise<void>;
+    onError?: (taskName: string, err: unknown) => void;
+};
+/**
+ * Start the scheduler for the given tasks. Uses setInterval for interval-based schedules
+ * and setTimeout for "at" schedules (day/week/month), then reschedules.
+ * Does not return; call from a long-running process.
+ */
+export declare function runScheduler(tasks: LoadedTask[], options?: RunSchedulerOptions): () => void;
+//# sourceMappingURL=runScheduler.d.ts.map

package/dist/runScheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runScheduler.d.ts","sourceRoot":"","sources":["../src/runScheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAG1D,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;CACpD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,EAAE,OAAO,GAAE,mBAAwB,GAAG,MAAM,IAAI,CAiD/F"}

package/dist/runScheduler.js

@@ -0,0 +1,58 @@
+import { getIntervalMs, isAtSchedule, getNextRunMs } from "./parseSchedule.js";
+/**
+ * Start the scheduler for the given tasks. Uses setInterval for interval-based schedules
+ * and setTimeout for "at" schedules (day/week/month), then reschedules.
+ * Does not return; call from a long-running process.
+ */
+export function runScheduler(tasks, options = {}) {
+    const ctx = options.ctx ?? {};
+    const onRun = options.onRun ?? null;
+    const onComplete = options.onComplete ?? null;
+    const onError = options.onError ?? ((name, err) => console.error(`[legonode task ${name}]`, err));
+    const timeouts = [];
+    const intervals = [];
+    function runTask(task) {
+        void (async () => {
+            try {
+                if (onRun)
+                    await onRun(task.name, ctx);
+                await task.run(ctx);
+                if (onComplete)
+                    await onComplete(task.name, ctx);
+            }
+            catch (err) {
+                onError(task.name, err);
+            }
+        })();
+    }
+    function scheduleAt(task, def) {
+        // Use at least 1s delay so we don't reschedule in the same second and risk multiple runs (e.g. hot reload).
+        const ms = Math.max(1000, getNextRunMs(def));
+        const t = setTimeout(() => {
+            runTask(task);
+            scheduleAt(task, def);
+        }, ms);
+        timeouts.push(t);
+    }
+    for (const task of tasks) {
+        for (const def of task.schedule) {
+            const intervalMs = getIntervalMs(def);
+            if (intervalMs !== null) {
+                // First run after intervalMs, then every intervalMs (no run at startup)
+                const t = setInterval(() => runTask(task), intervalMs);
+                intervals.push(t);
+                continue;
+            }
+            if (isAtSchedule(def)) {
+                scheduleAt(task, def);
+            }
+        }
+    }
+    return function stop() {
+        for (const t of timeouts)
+            clearTimeout(t);
+        for (const t of intervals)
+            clearInterval(t);
+    };
+}
+//# sourceMappingURL=runScheduler.js.map

package/dist/runScheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runScheduler.js","sourceRoot":"","sources":["../src/runScheduler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAS/E;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,KAAmB,EAAE,UAA+B,EAAE;IACjF,MAAM,GAAG,GAAgB,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC;IACpC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB,IAAI,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAClG,MAAM,QAAQ,GAAoC,EAAE,CAAC;IACrD,MAAM,SAAS,GAAqC,EAAE,CAAC;IAEvD,SAAS,OAAO,CAAC,IAAgB;QAC/B,KAAK,CAAC,KAAK,IAAI,EAAE;YACf,IAAI,CAAC;gBACH,IAAI,KAAK;oBAAE,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBACvC,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;gBACpB,IAAI,UAAU;oBAAE,MAAM,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACnD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC,CAAC,EAAE,CAAC;IACP,CAAC;IAED,SAAS,UAAU,CAAC,IAAgB,EAAE,GAAqC;QACzE,4GAA4G;QAC5G,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC;QAC7C,MAAM,CAAC,GAAG,UAAU,CAAC,GAAG,EAAE;YACxB,OAAO,CAAC,IAAI,CAAC,CAAC;YACd,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QACxB,CAAC,EAAE,EAAE,CAAC,CAAC;QACP,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,MAAM,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;YACtC,IAAI,UAAU,KAAK,IAAI,EAAE,CAAC;gBACxB,wEAAwE;gBACxE,MAAM,CAAC,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,CAAC;gBACvD,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;gBAClB,SAAS;YACX,CAAC;YACD,IAAI,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC;gBACtB,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,SAAS,IAAI;QAClB,KAAK,MAAM,CAAC,IAAI,QAAQ;YAAE,YAAY,CAAC,CAAC,CAAC,CAAC;QAC1C,KAAK,MAAM,CAAC,IAAI,SAAS;YAAE,aAAa,CAAC,CAAC,CAAC,CAAC;IAC9C,CAAC,CAAC;AACJ,CAAC"}

package/dist/scheduleLoader.d.ts

@@ -0,0 +1,14 @@
+import type { LoadedTask } from "./types.js";
+export type ScheduleRunnerFn = (name: string, payload?: unknown) => void | Promise<void>;
+/** Build a runner that invokes a schedule's run by name (e.g. "interval.example"). */
+export declare function createScheduleRunner(tasks: LoadedTask[]): ScheduleRunnerFn;
+export declare function getOrCreateScheduleRunner(appDir: string): Promise<ScheduleRunnerFn>;
+export declare function clearScheduleRunnerCache(appDir?: string): void;
+export type ScannedSchedule = {
+    name: string;
+    filePath: string;
+};
+export declare function scanScheduleFiles(appDir: string): ScannedSchedule[];
+export declare function loadScheduleModule(filePath: string, cacheBust?: string): Promise<LoadedTask | null>;
+export declare function loadSchedulesFromApp(appDir: string, cacheBust?: string): Promise<LoadedTask[]>;
+//# sourceMappingURL=scheduleLoader.d.ts.map

package/dist/scheduleLoader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduleLoader.d.ts","sourceRoot":"","sources":["../src/scheduleLoader.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAyB,UAAU,EAA0B,MAAM,YAAY,CAAC;AAuB5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAIzF,sFAAsF;AACtF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,gBAAgB,CAc1E;AAED,wBAAsB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,CASzF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAG9D;AAOD,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC;AAEjE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,EAAE,CAoBnE;AAED,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAmB5B;AAED,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,EAAE,CAAC,CAQvB"}

package/dist/scheduleLoader.js

@@ -0,0 +1,122 @@
+import { readdirSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { pathToFileURL } from "node:url";
+import { invalidateModuleCache } from "./moduleCache.js";
+const CRON_EXTENSIONS = [".cron.ts", ".cron.js", ".cron.mts", ".cron.mjs"];
+const CRON_DIR = "cron";
+/** Convert task name (e.g. intervalExample) to schedule name (e.g. interval.example). */
+function toScheduleName(name) {
+    if (!name.length)
+        return "";
+    const parts = [];
+    let current = name[0].toLowerCase();
+    for (let i = 1; i < name.length; i++) {
+        const c = name[i];
+        if (c >= "A" && c <= "Z") {
+            parts.push(current);
+            current = c.toLowerCase();
+        }
+        else {
+            current += c;
+        }
+    }
+    parts.push(current);
+    return parts.join(".");
+}
+const scheduleRunnerCache = new Map();
+/** Build a runner that invokes a schedule's run by name (e.g. "interval.example"). */
+export function createScheduleRunner(tasks) {
+    const byName = new Map();
+    for (const task of tasks) {
+        byName.set(toScheduleName(task.name), task);
+    }
+    return (name, payload) => {
+        const task = byName.get(name);
+        if (!task) {
+            console.warn(`[legonode] schedule not found: "${name}"`);
+            return;
+        }
+        const ctx = { payload };
+        return Promise.resolve(task.run(ctx));
+    };
+}
+export async function getOrCreateScheduleRunner(appDir) {
+    const key = resolve(appDir);
+    let runner = scheduleRunnerCache.get(key);
+    if (runner)
+        return runner;
+    const cacheBust = typeof process !== "undefined" ? process.env.LEGONODE_CRON_RELOAD_TOKEN : undefined;
+    const tasks = await loadSchedulesFromApp(appDir, cacheBust);
+    runner = createScheduleRunner(tasks);
+    scheduleRunnerCache.set(key, runner);
+    return runner;
+}
+export function clearScheduleRunnerCache(appDir) {
+    if (appDir)
+        scheduleRunnerCache.delete(resolve(appDir));
+    else
+        scheduleRunnerCache.clear();
+}
+function normalizeSchedule(schedule) {
+    if (Array.isArray(schedule))
+        return schedule;
+    return [schedule];
+}
+export function scanScheduleFiles(appDir) {
+    const base = resolve(appDir, CRON_DIR);
+    const list = [];
+    let entries;
+    try {
+        entries = readdirSync(base, { withFileTypes: true }).map((e) => ({
+            name: e.name,
+            isFile: e.isFile()
+        }));
+    }
+    catch {
+        return list;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile)
+            continue;
+        const ext = CRON_EXTENSIONS.find((e) => entry.name.endsWith(e));
+        if (!ext)
+            continue;
+        const name = entry.name.slice(0, -ext.length);
+        list.push({ name, filePath: join(base, entry.name) });
+    }
+    return list;
+}
+export async function loadScheduleModule(filePath, cacheBust) {
+    try {
+        if (cacheBust)
+            invalidateModuleCache(filePath);
+        const url = pathToFileURL(filePath).href;
+        const importUrl = cacheBust ? `${url}?t=${cacheBust}` : url;
+        const mod = await import(importUrl);
+        const schedule = mod.schedule;
+        const run = mod.run;
+        if (schedule == null || typeof run !== "function")
+            return null;
+        const scheduleList = normalizeSchedule(schedule);
+        const name = (mod.name ?? basename(filePath).replace(/\.cron\.(ts|js|mts|mjs)$/i, "")) || "task";
+        return {
+            name,
+            schedule: scheduleList,
+            run: run
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function loadSchedulesFromApp(appDir, cacheBust) {
+    const scanned = scanScheduleFiles(appDir);
+    const tasks = [];
+    for (const { filePath } of scanned) {
+        const task = await loadScheduleModule(filePath, cacheBust);
+        if (task)
+            tasks.push(task);
+    }
+    return tasks;
+}
+//# sourceMappingURL=scheduleLoader.js.map

package/dist/scheduleLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduleLoader.js","sourceRoot":"","sources":["../src/scheduleLoader.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,37 @@
+/**
+ * JSON-based schedule definition (no cron strings).
+ * Supports: every minute/hour, every day at, every week day at, every month date at, or interval (e.g. "5m", "10s").
+ */
+export type ScheduleDef = {
+    every: "minute";
+} | {
+    every: "hour";
+} | {
+    every: "day";
+    at?: string;
+} | {
+    every: "week";
+    day?: string;
+    at?: string;
+} | {
+    every: "month";
+    date?: number;
+    at?: string;
+} | {
+    every: string;
+};
+/** One task can have multiple schedules. */
+export type Schedule = ScheduleDef | ScheduleDef[];
+export type TaskContext = {
+    /** Reserved for app-specific services (e.g. db, reportService). */
+    services?: Record<string, unknown>;
+    /** Set when the schedule is triggered via ctx.schedule(name, payload). */
+    payload?: unknown;
+};
+export type TaskRunFn = (ctx: TaskContext) => void | Promise<void>;
+export type LoadedTask = {
+    name: string;
+    schedule: ScheduleDef[];
+    run: TaskRunFn;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,QAAQ,CAAA;CAAE,GACnB;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GACjB;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtB,4CAA4C;AAC5C,MAAM,MAAM,QAAQ,GAAG,WAAW,GAAG,WAAW,EAAE,CAAC;AAEnD,MAAM,MAAM,WAAW,GAAG;IACxB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnE,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,GAAG,EAAE,SAAS,CAAC;CAChB,CAAC"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@legonode/cron",
+  "version": "0.0.1",
+  "description": "Cron schedules, loader, and runner for Legonode apps (app/cron/*.cron.ts)",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "legonode": ">=0.0.4"
+  },
+  "devDependencies": {
+    "legonode": "workspace:*"
+  }
+}