@warlock.js/scheduler 4.0.171 → 4.1.1

package/skills/schedule-fluently/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: schedule-fluently
+description: 'Build a job schedule via `every*` / `daily` / `weekly` / `monthly` / `at` / `on` / `beginOf` / `endOf`. Triggers: `.everyMinutes`, `.daily`, `.weekly`, `.monthly`, `.at`, `.on`, `.every`, `.beginOf`, `.endOf`, `.twiceDaily`, `scheduler.newJob`; "run every 5 minutes", "daily at 3am", "monday standup", "first of every month", "last day of month"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: cron — `@warlock.js/scheduler/schedule-with-cron/SKILL.md`; timezone — `@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`; retry — `@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`; competing `node-cron`, `node-schedule`, `agenda`; native `setInterval`.'
+---
+
+# Fluent scheduling API
+
+Chainable methods on a `Job` instance. Each method returns `this` for chaining; each call recomputes `job.nextRun` on the spot.
+
+## Preset intervals
+
+| Method               | Equivalent of            | Notes                          |
+| -------------------- | ------------------------ | ------------------------------ |
+| `.everySecond()`     | `.every(1, "second")`    | High frequency — use sparingly |
+| `.everySeconds(N)`   | `.every(N, "second")`    |                                |
+| `.everyMinute()`     | `.every(1, "minute")`    |                                |
+| `.everyMinutes(N)`   | `.every(N, "minute")`    |                                |
+| `.everyHour()`       | `.every(1, "hour")`      |                                |
+| `.everyHours(N)`     | `.every(N, "hour")`      |                                |
+| `.everyDay()`        | `.every(1, "day")`       | Same as `.daily()`             |
+| `.daily()`           | `.every(1, "day")`       |                                |
+| `.twiceDaily()`      | `.every(12, "hour")`     | Every 12 hours                 |
+| `.everyWeek()`       | `.every(1, "week")`      | Same as `.weekly()`            |
+| `.weekly()`          | `.every(1, "week")`      |                                |
+| `.everyMonth()`      | `.every(1, "month")`     | Same as `.monthly()`           |
+| `.monthly()`         | `.every(1, "month")`     |                                |
+| `.everyYear()`       | `.every(1, "year")`      | Same as `.yearly()`            |
+| `.yearly()`          | `.every(1, "year")`      |                                |
+| `.always()`          | `.every(1, "minute")`    | Continuous "tick" jobs         |
+
+## Custom intervals — `.every(value, unit)`
+
+```ts
+job("t", task).every(5, "minute");
+job("t", task).every(2, "hour");
+job("t", task).every(3, "day");
+```
+
+Units: `"second" | "minute" | "hour" | "day" | "week" | "month" | "year"`.
+
+**Validation.** `every(value, unit)` throws at definition time if `value` is `0`, negative, `NaN`, or `Infinity`. This guards against the misconfigured-interval class of bugs that would otherwise spin the scheduler.
+
+## Target a specific time — `.at("HH:mm" | "HH:mm:ss")`
+
+```ts
+job("nightly", fn).daily().at("03:00");
+job("midday",  fn).daily().at("12:30:15");
+```
+
+**Validation.** `.at()` throws if the format is malformed (`"foo"`, `"9-30"`), or any component is out of range (hour > 23, minute > 59, second > 59).
+
+## Target a specific day — `.on(day)`
+
+Day-of-week (string) or day-of-month (number 1–31):
+
+```ts
+job("monday-standup", task).weekly().on("monday");
+job("mid-month-sync", task).monthly().on(15);
+job("end-of-month",   task).monthly().on(31);    // see beginOf/endOf for the right way
+```
+
+Valid day-of-week strings: `"sunday"`, `"monday"`, `"tuesday"`, `"wednesday"`, `"thursday"`, `"friday"`, `"saturday"`.
+
+**Validation.** Numeric `on(N)` throws if `N < 1 || N > 31`.
+
+**Gotcha.** `monthly().on(31)` clamps to the actual month length in dayjs — February runs are unpredictable. Use `endOf("month")` for "last day" semantics instead.
+
+## Boundary shortcuts — `.beginOf(type)` / `.endOf(type)`
+
+Both accept `"day" | "month" | "year"`.
+
+| Method               | Fires at                                          |
+| -------------------- | ------------------------------------------------- |
+| `beginOf("day")`     | 00:00 every day                                   |
+| `endOf("day")`       | 23:59 every day                                   |
+| `beginOf("month")`   | 1st of every month at 00:00                       |
+| `endOf("month")`     | Last day of every month at 23:59 (**dynamic**)    |
+| `beginOf("year")`    | January 1 at 00:00 every year                     |
+| `endOf("year")`      | December 31 at 23:59 every year                   |
+
+**`endOf("month")` is dynamic** — recomputes per cycle, so a job defined in February (28 days) still fires on March 31, April 30, etc. Leap years pick Feb 29 correctly.
+
+**`beginOf("year")` / `endOf("year")` lock the month** — always Jan 1 / Dec 31, never "1st/31st of whatever month the job was defined in."
+
+## Cron is an alternative, not an addition
+
+`.cron("…")` clears any prior interval/`at`/`on`/`beginOf`/`endOf` config — and vice versa. They're mutually exclusive. See [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md).
+
+## Chaining order doesn't matter (for the most part)
+
+Every fluent method recomputes `nextRun` at the end. Putting `.at()` before `.daily()` produces the same schedule as putting `.daily()` before `.at()` — but for readability, the conventional order is **interval → day → time → timezone → execution options**:
+
+```ts
+job("good", fn)
+  .weekly()              // interval
+  .on("monday")          // day
+  .at("09:00")           // time
+  .inTimezone("UTC")     // timezone
+  .preventOverlap()      // execution
+  .retry(3, 1000);       // execution
+```
+
+## Inline registration — `scheduler.newJob()`
+
+For one-liners, the scheduler exposes a `newJob()` shortcut that creates, registers, and returns the job in one call:
+
+```ts
+scheduler
+  .newJob("cleanup", cleanupFn)
+  .daily()
+  .at("03:00");
+```
+
+To register several pre-built jobs at once, `scheduler.addJobs([...])` is the batch counterpart to `addJob` (both are chainable and preserve insertion order):
+
+```ts
+scheduler.addJobs([
+  job("cleanup", cleanupFn).daily().at("03:00"),
+  job("reports", sendReports).weekly().on("monday").at("09:00"),
+]);
+```
+
+If the scheduler is already running, every job added via `addJob` / `addJobs` is prepared on the spot (its `nextRun` is computed) so it fires on the next tick.
+
+## Reading state at runtime
+
+```ts
+const j = scheduler.getJob("nightly-cleanup");
+
+j?.nextRun?.toISOString();   // next scheduled run (Dayjs)
+j?.lastRun?.toISOString();   // last attempt — success OR failure
+j?.isRunning;                // currently executing?
+j?.intervals;                // { every?, day?, dayOfMonthMode?, month?, time? } (readonly)
+j?.cronExpression;           // null if using fluent API
+```
+
+## See also
+
+- [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md) — when the fluent API isn't enough
+- [`@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md) — `.retry()` and `.preventOverlap()` on the same job
+- [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md) — `.inTimezone()`

package/skills/schedule-with-cron/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: schedule-with-cron
+description: 'Write `.cron(''…'')` expressions — 5-field syntax, operators (`*` `,` `-` `/`), Vixie OR semantics for DOM / DOW, `parseCron()` preview utility. Triggers: `.cron`, `parseCron`, `CronParser`, `*/5 * * * *`, `0 9 * * 1-5`; "write a cron expression", "every weekday at 9am cron", "preview next cron run", "migrate crontab(5) entry"; typical import `import { parseCron } from "@warlock.js/scheduler"`. Skip: human-readable schedules — `@warlock.js/scheduler/schedule-fluently/SKILL.md`; timezone — `@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`; competing libs `node-cron`, `cron`, `croner`, `cronstrue`.'
+---
+
+# Cron expressions
+
+The escape hatch when the fluent API can't express a schedule. Activating `.cron()` clears any prior fluent config — the two are mutually exclusive.
+
+## 5-field syntax
+
+```
+┌───────────── minute        (0-59)
+│ ┌───────────── hour          (0-23)
+│ │ ┌───────────── day-of-month (1-31)
+│ │ │ ┌───────────── month        (1-12)
+│ │ │ │ ┌───────────── day-of-week  (0-6, Sunday = 0)
+│ │ │ │ │
+* * * * *
+```
+
+**Note:** Sunday is `0` only. Some cron dialects also accept `7` for Sunday — this parser does NOT.
+
+## Operators
+
+| Syntax    | Meaning                       | Example          |
+| --------- | ----------------------------- | ---------------- |
+| `*`       | Any value (full range)        | `* * * * *`      |
+| `5`       | Single value                  | `30 14 * * *`    |
+| `1,3,5`   | List                          | `0,30 * * * *`   |
+| `1-5`     | Inclusive range               | `0 9-17 * * *`   |
+| `*/N`     | Step over the wildcard        | `*/5 * * * *`    |
+| `A-B/N`   | Step over a range             | `0 1-10/2 * * *` |
+
+**Not supported (yet):** named tokens (`MON-FRI`, `JAN-DEC`), special strings (`@daily`, `@hourly`, `@reboot`), seconds field (6-field), Quartz modifiers (`L`, `W`, `#`).
+
+## Day-of-month + day-of-week — Vixie OR semantics
+
+When **both** `dayOfMonth` AND `dayOfWeek` are restricted (neither is `*`), the date matches if **either** constraint matches. When one is `*` and the other is restricted, only the restricted one matters.
+
+```ts
+// "1st of month OR any Monday" — fires on the 1st even if not a Monday,
+// AND fires on any Monday even if not the 1st.
+job("digest", sendDigest).cron("0 0 1 * 1");
+
+// "15th of month" — DOW is *, so only DOM applies. Fires only on the 15th.
+job("midmonth", task).cron("0 0 15 * *");
+
+// "Every Monday" — DOM is *, so only DOW applies. Fires only on Mondays.
+job("monday-only", task).cron("0 0 * * 1");
+```
+
+This matches Vixie cron (the de facto standard on Unix). Migrating an existing cron table from `crontab(5)` should "just work" semantically.
+
+## Common recipes
+
+```ts
+// Every 5 minutes
+.cron("*/5 * * * *")
+
+// Top of every hour
+.cron("0 * * * *")
+
+// Every weekday at 9 AM
+.cron("0 9 * * 1-5")
+
+// 2:30 PM on the 15th of every month
+.cron("30 14 15 * *")
+
+// Every 2 hours, on the hour
+.cron("0 */2 * * *")
+
+// First day of each month at midnight
+.cron("0 0 1 * *")
+```
+
+## Validation
+
+`new CronParser(expr)` and `.cron(expr)` both throw at definition time on:
+
+- Wrong field count (must be exactly 5)
+- Non-numeric values, out-of-range values, inverted ranges (`5-1`)
+- Step `<= 0`, non-numeric step
+- Impossible day-of-month / month combinations — a date that can never occur, e.g. `0 0 30 2 *` (Feb 30) or `0 0 31 4 *` (April has 30 days). Rejected with an `Impossible cron expression` error.
+
+```ts
+new CronParser("0 0 30 2 *"); // throws: Impossible cron expression — Feb never has a 30th
+new CronParser("0 0 31 4 *"); // throws: April has only 30 days
+```
+
+**Leap years and the OR escape hatch.** `0 0 29 2 *` (Feb 29) is **accepted** — it occurs in leap years. And when day-of-week is also restricted, Vixie OR semantics keep the schedule alive via the weekday path, so the combo is never rejected: `0 0 30 2 1` (Feb 30 OR any Monday) parses fine and fires on Mondays.
+
+Throws are eager — bad expressions fail fast at construction, not at first tick.
+
+## Standalone preview — `parseCron()`
+
+The `CronParser` class is exported as a utility for ad-hoc next-run calculation, separate from any job:
+
+```ts
+import { parseCron } from "@warlock.js/scheduler";
+import dayjs from "dayjs";
+
+const parser = parseCron("0 9 * * 1-5");
+
+parser.nextRun().toISOString();              // next weekday at 9 AM
+parser.nextRun(dayjs("2026-12-31")).format(); // from a specific anchor
+
+parser.matches(dayjs());                     // is "now" a fire moment?
+
+parser.fields;                                // parsed numeric arrays
+parser.expression;                            // original string
+```
+
+Impossible expressions are rejected eagerly at construction (see Validation), so `nextRun(from?)` always resolves a satisfiable expression within a year — its one-year scan bound is just a defensive backstop, never the path that catches a bad expression.
+
+## Timezone interaction
+
+If the job has `.inTimezone(tz)`, the cron parser receives a timezone-aware `dayjs` object — so `0 9 * * *` with `.inTimezone("Asia/Tokyo")` fires at 09:00 JST. See [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md).
+
+## See also
+
+- [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) — the higher-level alternative for human-readable schedules
+- [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md) — pinning a cron schedule to a wall-clock timezone

package/skills/scheduler-basics/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: scheduler-basics
+description: 'Start with `@warlock.js/scheduler` — `job()` factory + `scheduler` singleton, 2-primitive surface, UTC default, factory-first API. Triggers: `job`, `scheduler`, `scheduler.addJob`, `scheduler.start`, `scheduler.newJob`; "schedule a recurring job", "how to use warlock scheduler", "where do I start"; typical import `import { job, scheduler } from "@warlock.js/scheduler"`. Skip: fluent — `@warlock.js/scheduler/schedule-fluently/SKILL.md`; cron — `@warlock.js/scheduler/schedule-with-cron/SKILL.md`; retry — `@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`; events — `@warlock.js/scheduler/observe-scheduler/SKILL.md`; timezone — `@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`; competing `bullmq`, `agenda`, `node-cron`; native `setInterval`.'
+---
+
+# Schedule recurring jobs
+
+In-process recurring job scheduler. Built on `dayjs`. Two primitives, factory-first API, type-safe events.
+
+> This skill is the scheduler **map** — read it first, then load the specific skill for the task.
+
+## The 2-primitive surface
+
+```
+Job          → the scheduled unit          (factory: `job(name, callback)`)
+Scheduler    → the runtime / tick loop     (singleton: `scheduler` | class: `new Scheduler()`)
+```
+
+A `Job` carries the schedule (interval or cron), retry config, overlap rule, timezone, and the callback. A `Scheduler` owns the tick loop, the registered jobs, the parallel/sequential execution mode, and emits lifecycle events. The exported `CronParser` is a utility for ad-hoc cron preview — not part of the scheduling flow.
+
+## Install
+
+```bash
+yarn add @warlock.js/scheduler
+```
+
+## Foundations
+
+The 9 things that are true in every scheduler use:
+
+1. **Factory-first.** `import { job, scheduler } from "@warlock.js/scheduler"`. Users do not call `new Job()` directly (it works, but `job()` is the documented surface).
+2. **Default timezone is UTC.** `daily().at("09:00")` fires at 09:00 UTC, regardless of the server's clock. Pin a job to wall-clock with `.inTimezone("America/New_York")`. See [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md).
+3. **The scheduler awaits each tick.** Concurrent same-job runs from the scheduler's own loop are structurally impossible. `preventOverlap()` is for jobs that ALSO get invoked outside the loop. See [`@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md).
+4. **Cron uses 5-field Vixie semantics.** When both `dayOfMonth` and `dayOfWeek` are restricted (neither is `*`), a date matches if EITHER constraint matches. Standard-cron compatible. See [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md).
+5. **`nextRun` always advances after a run — success OR failure.** A permanently failing job re-fires on its next scheduled slot, not on every tick.
+6. **Validation throws at definition time.** `every(0)`, `at("24:00")`, `on(32)`, `retry(-1)`, malformed cron — all throw immediately when you wire the job, not at runtime.
+7. **`Job.run()` returns a `JobResult`, never throws.** Errors funnel into `result.error`. The scheduler emits `job:error` after all retries are exhausted.
+8. **Parallel mode is within a tick, not across.** Even with `runInParallel(true)`, the NEXT tick waits for the current tick's jobs to all settle.
+9. **Tick interval is drift-compensated.** A tick that takes 200 ms is followed by an 800 ms delay so the cadence between tick *starts* averages `tickInterval`, not `tickInterval + work-time`.
+
+## 30-second example
+
+```ts
+import { scheduler, job } from "@warlock.js/scheduler";
+
+scheduler.on("job:error", (name, error) => logger.error({ name, error }));
+
+scheduler.addJob(
+  job("nightly-cleanup", async () => {
+    await db.deleteExpiredTokens();
+  })
+    .daily()
+    .at("03:00")
+    .inTimezone("America/New_York")
+    .preventOverlap()
+    .retry(3, 1000)
+);
+
+scheduler.start();
+
+process.on("SIGTERM", async () => {
+  await scheduler.shutdown(30_000);
+  process.exit(0);
+});
+```
+
+## Pick a skill
+
+| If the task is about… | Load |
+| --- | --- |
+| Building schedules via `every*`/`daily`/`weekly`/`monthly`/`at`/`on`/`beginOf`/`endOf` | [`@warlock.js/scheduler/schedule-fluently/SKILL.md`](@warlock.js/scheduler/schedule-fluently/SKILL.md) |
+| Writing `.cron("…")` expressions, debugging DOM/DOW behavior, using `parseCron()` for preview | [`@warlock.js/scheduler/schedule-with-cron/SKILL.md`](@warlock.js/scheduler/schedule-with-cron/SKILL.md) |
+| Configuring `.retry()` / exponential backoff, `.preventOverlap()`, understanding failure rescheduling | [`@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md`](@warlock.js/scheduler/configure-retry-and-overlap/SKILL.md) |
+| Subscribing to scheduler events, reading `JobResult`, lifecycle, graceful shutdown | [`@warlock.js/scheduler/observe-scheduler/SKILL.md`](@warlock.js/scheduler/observe-scheduler/SKILL.md) |
+| Per-job `.inTimezone()`, multi-region patterns, DST handling | [`@warlock.js/scheduler/pin-schedule-timezone/SKILL.md`](@warlock.js/scheduler/pin-schedule-timezone/SKILL.md) |
+
+## When NOT to use this skill
+
+- Jobs imported from `bullmq`, `agenda`, `node-cron`, etc. — those are different libraries.
+- Long-running queue workers (consumer processes) — this is a scheduler, not a queue.
+- One-off "run this at a specific date once" — currently not supported (on the backlog as `runAt()`).
+- Multi-replica deployments needing leader election — also on the backlog (distributed locking).
+
+## Package structure
+
+```
+@warlock.js/scheduler
+  src/
+    index.ts        — barrel: Scheduler, scheduler, Job, job, CronParser, parseCron, types
+    scheduler.ts    — Scheduler class + default singleton
+    job.ts          — Job class + job() factory
+    cron-parser.ts  — CronParser class + parseCron() factory
+    types.ts        — TimeType, Day, JobIntervals, JobResult, RetryConfig, SchedulerEvents
+```

package/cjs/cron-parser.d.ts

@@ -1,98 +0,0 @@
-import { type Dayjs } from "dayjs";
-/**
- * Parsed cron expression fields
- */
-export type CronFields = {
-    /** Minutes (0-59) */
-    minutes: number[];
-    /** Hours (0-23) */
-    hours: number[];
-    /** Days of month (1-31) */
-    daysOfMonth: number[];
-    /** Months (1-12) */
-    months: number[];
-    /** Days of week (0-6, Sunday = 0) */
-    daysOfWeek: number[];
-};
-/**
- * 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
- *
- * @example
- * ```typescript
- * const parser = new CronParser("0 9 * * 1-5"); // 9 AM weekdays
- * const nextRun = parser.nextRun();
- * ```
- */
-export declare class CronParser {
-    private readonly _expression;
-    private readonly _fields;
-    /**
-     * Creates a new CronParser instance
-     *
-     * @param expression - Standard 5-field cron expression
-     * @throws Error if expression is invalid
-     */
-    constructor(_expression: string);
-    /**
-     * Get the parsed cron fields
-     */
-    get fields(): Readonly<CronFields>;
-    /**
-     * Get the original expression
-     */
-    get expression(): string;
-    /**
-     * Calculate the next run time from a given date
-     *
-     * @param from - Starting date (defaults to now)
-     * @returns Next run time as Dayjs
-     */
-    nextRun(from?: Dayjs): Dayjs;
-    /**
-     * Check if a given date matches the cron expression
-     *
-     * @param date - Date to check
-     * @returns true if the date matches
-     */
-    matches(date: Dayjs): boolean;
-    /**
-     * Parse a cron expression into fields
-     */
-    private _parse;
-    /**
-     * 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
-     */
-    private _parseField;
-}
-/**
- * Parse a cron expression string
- *
- * @param expression - Cron expression (5 fields)
- * @returns CronParser instance
- */
-export declare function parseCron(expression: string): CronParser;
-//# sourceMappingURL=cron-parser.d.ts.map

package/cjs/cron-parser.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cron-parser.d.ts","sourceRoot":"","sources":["../src/cron-parser.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,KAAK,EAAE,MAAM,OAAO,CAAC;AAE1C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,qBAAqB;IACrB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,mBAAmB;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2BAA2B;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,oBAAoB;IACpB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,qCAAqC;IACrC,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,UAAU;IASF,OAAO,CAAC,QAAQ,CAAC,WAAW;IAR/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IAErC;;;;;OAKG;gBACiC,WAAW,EAAE,MAAM;IAIvD;;OAEG;IACH,IAAW,MAAM,IAAI,QAAQ,CAAC,UAAU,CAAC,CAExC;IAED;;OAEG;IACH,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED;;;;;OAKG;IACI,OAAO,CAAC,IAAI,GAAE,KAAe,GAAG,KAAK;IA+C5C;;;;;OAKG;IACI,OAAO,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO;IAUpC;;OAEG;IACH,OAAO,CAAC,MAAM;IAoBd;;;;;;;OAOG;IACH,OAAO,CAAC,WAAW;CA2DpB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU,CAExD"}

package/cjs/cron-parser.js

@@ -1,193 +0,0 @@
-'use strict';var dayjs=require('dayjs');function _interopDefault(e){return e&&e.__esModule?e:{default:e}}var dayjs__default=/*#__PURE__*/_interopDefault(dayjs);/**
- * 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
- *
- * @example
- * ```typescript
- * const parser = new CronParser("0 9 * * 1-5"); // 9 AM weekdays
- * const nextRun = parser.nextRun();
- * ```
- */
-class CronParser {
-    _expression;
-    _fields;
-    /**
-     * Creates a new CronParser instance
-     *
-     * @param expression - Standard 5-field cron expression
-     * @throws Error if expression is invalid
-     */
-    constructor(_expression) {
-        this._expression = _expression;
-        this._fields = this._parse(_expression);
-    }
-    /**
-     * 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 = dayjs__default.default()) {
-        let date = from.add(1, "minute").second(0).millisecond(0);
-        // Maximum iterations to prevent infinite loops
-        const maxIterations = 366 * 24 * 60; // 1 year of minutes
-        let iterations = 0;
-        while (iterations < maxIterations) {
-            iterations++;
-            // Check month
-            if (!this._fields.months.includes(date.month() + 1)) {
-                date = date.add(1, "month").date(1).hour(0).minute(0);
-                continue;
-            }
-            // Check day of month
-            if (!this._fields.daysOfMonth.includes(date.date())) {
-                date = date.add(1, "day").hour(0).minute(0);
-                continue;
-            }
-            // Check day of week
-            if (!this._fields.daysOfWeek.includes(date.day())) {
-                date = date.add(1, "day").hour(0).minute(0);
-                continue;
-            }
-            // Check hour
-            if (!this._fields.hours.includes(date.hour())) {
-                date = date.add(1, "hour").minute(0);
-                continue;
-            }
-            // Check minute
-            if (!this._fields.minutes.includes(date.minute())) {
-                date = date.add(1, "minute");
-                continue;
-            }
-            // All fields match!
-            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.daysOfMonth.includes(date.date()) &&
-            this._fields.months.includes(date.month() + 1) &&
-            this._fields.daysOfWeek.includes(date.day()));
-    }
-    /**
-     * Parse a cron expression into fields
-     */
-    _parse(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;
-        return {
-            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),
-        };
-    }
-    /**
-     * 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 = new Set();
-        // Handle lists (e.g., "1,3,5")
-        const parts = field.split(",");
-        for (const part of parts) {
-            // Handle step values (e.g., "*/5" or "1-10/2")
-            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 === "*") {
-                // Wildcard - all values
-                rangeStart = min;
-                rangeEnd = max;
-            }
-            else if (range.includes("-")) {
-                // Range (e.g., "1-5")
-                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 {
-                // Single value
-                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;
-            }
-            // Add values with step
-            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);
-}exports.CronParser=CronParser;exports.parseCron=parseCron;//# sourceMappingURL=cron-parser.js.map

package/cjs/cron-parser.js.map

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