@warlock.js/scheduler 4.0.174 → 4.1.2

package/esm/job.d.mts

@@ -0,0 +1,386 @@
+import { Day, JobIntervals, JobResult, TimeType } from "./types.mjs";
+import { Dayjs } from "dayjs";
+
+//#region ../../@warlock.js/scheduler/src/job.d.ts
+type JobCallback = (job: Job) => Promise<any>;
+/**
+ * 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);
+ * ```
+ */
+declare class Job {
+  readonly name: string;
+  private readonly _callback;
+  /**
+   * Interval configuration for scheduling
+   */
+  private _intervals;
+  /**
+   * Last execution timestamp.
+   *
+   * Updated after every run attempt — successful or failed — so the next-run
+   * calculation always advances even when a job throws. Use the `job:complete`
+   * / `job:error` events if you need to distinguish success from failure.
+   */
+  private _lastRun;
+  /**
+   * Whether the job is currently executing
+   */
+  private _isRunning;
+  /**
+   * Skip execution if job is already running
+   */
+  private _skipIfRunning;
+  /**
+   * Retry configuration
+   */
+  private _retryConfig;
+  /**
+   * Timezone for scheduling (defaults to UTC)
+   */
+  private _timezone;
+  /**
+   * Cron expression parser (mutually exclusive with interval config)
+   */
+  private _cronParser;
+  /**
+   * All pending `waitForCompletion()` resolvers — drained on every run end.
+   */
+  private _completionResolvers;
+  /**
+   * Next scheduled execution time
+   */
+  nextRun: Dayjs | null;
+  /**
+   * Creates a new Job instance
+   *
+   * @param name - Unique identifier for the job
+   * @param callback - Function to execute when the job runs
+   */
+  constructor(name: string, _callback: JobCallback);
+  /**
+   * Returns true if the job is currently executing
+   */
+  get isRunning(): boolean;
+  /**
+   * Returns the last execution timestamp (success OR failure).
+   */
+  get lastRun(): Dayjs | null;
+  /**
+   * Returns the current interval configuration (readonly)
+   */
+  get intervals(): Readonly<JobIntervals>;
+  /**
+   * 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: number, timeType: TimeType): this;
+  /**
+   * Run job every second (use with caution - high frequency)
+   */
+  everySecond(): this;
+  /**
+   * Run job every specified number of seconds
+   */
+  everySeconds(seconds: number): this;
+  /**
+   * Run job every minute
+   */
+  everyMinute(): this;
+  /**
+   * Run job every specified number of minutes
+   */
+  everyMinutes(minutes: number): this;
+  /**
+   * Run job every hour
+   */
+  everyHour(): this;
+  /**
+   * Run job every specified number of hours
+   */
+  everyHours(hours: number): this;
+  /**
+   * Run job every day at midnight
+   */
+  everyDay(): this;
+  /**
+   * Alias for everyDay()
+   */
+  daily(): this;
+  /**
+   * Run job twice a day (every 12 hours)
+   */
+  twiceDaily(): this;
+  /**
+   * Run job every week
+   */
+  everyWeek(): this;
+  /**
+   * Alias for everyWeek()
+   */
+  weekly(): this;
+  /**
+   * Run job every month
+   */
+  everyMonth(): this;
+  /**
+   * Alias for everyMonth()
+   */
+  monthly(): this;
+  /**
+   * Run job every year
+   */
+  everyYear(): this;
+  /**
+   * Alias for everyYear()
+   */
+  yearly(): this;
+  /**
+   * Alias for everyMinute() - job runs continuously every minute
+   */
+  always(): this;
+  /**
+   * 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: string): this;
+  /**
+   * Get the cron expression if one is set
+   */
+  get cronExpression(): string | 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: Day | number): 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: string): 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: TimeType): this;
+  /**
+   * 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: TimeType): this;
+  /**
+   * 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: string): 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?: boolean): 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: number, delay?: number, backoffMultiplier?: number): this;
+  /**
+   * Terminate the job and clear all scheduling data
+   */
+  terminate(): this;
+  /**
+   * Prepare the job by calculating the next run time
+   * Called by the scheduler when starting
+   */
+  prepare(): void;
+  /**
+   * 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(): boolean;
+  /**
+   * 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(): boolean;
+  /**
+   * 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
+   */
+  run(): Promise<JobResult>;
+  /**
+   * 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(): Promise<void>;
+  /**
+   * Get current time, respecting the configured timezone.
+   */
+  private _now;
+  /**
+   * Execute the callback with retry logic
+   */
+  private _executeWithRetry;
+  /**
+   * Calculate retry delay with optional exponential backoff
+   */
+  private _calculateRetryDelay;
+  /**
+   * Sleep for specified milliseconds
+   */
+  private _sleep;
+  /**
+   * 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.
+   */
+  private _applyConstraints;
+  /**
+   * 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.
+   */
+  private _determineNextRun;
+}
+/**
+ * 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");
+ * ```
+ */
+declare function job(name: string, callback: JobCallback): Job;
+//#endregion
+export { Job, JobCallback, job };
+//# sourceMappingURL=job.d.mts.map

package/esm/job.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.d.mts","names":[],"sources":["../../../../../@warlock.js/scheduler/src/job.ts"],"mappings":";;;;KAWY,WAAA,IAAe,GAAA,EAAK,GAAA,KAAQ,OAAO;;AAA/C;;;;;;;;AAA+C;AA4D/C;;;;;cAAa,GAAA;EAAA,SAqEO,IAAA;EAAA,iBACC,SAAA;EA8CmB;;;EAAA,QA5G9B,UAAA;EA6hBoB;;;;;;;EAAA,QAphBpB,QAAA;EAAA;;;EAAA,QAKA,UAAA;EAeA;;;EAAA,QAVA,cAAA;EA6BQ;;;EAAA,QAxBR,YAAA;EAsCW;;;EAAA,QAjCX,SAAA;EAyDG;;;EAAA,QApDH,WAAA;EA0EK;;;EAAA,QArEL,oBAAA;EA4FD;;;EAnFA,OAAA,EAAS,KAAA;EAiGI;;;;;;cApFF,IAAA,UACC,SAAA,EAAW,WAAA;EA6HvB;;;EAAA,IAnHI,SAAA,CAAA;EA+IJ;;;EAAA,IAxII,OAAA,CAAA,GAAW,KAAA;EA2LV;;;EAAA,IApLD,SAAA,CAAA,GAAa,QAAA,CAAS,YAAA;EAmNvB;;;;;;;;;;;;;;EA7LH,KAAA,CAAM,KAAA,UAAe,QAAA,EAAU,QAAA;EA4VL;;;EA5U1B,WAAA,CAAA;EAoYA;;;EA7XA,YAAA,CAAa,OAAA;EA0ZQ;;;EAnZrB,WAAA,CAAA;EA2dO;;;EApdP,YAAA,CAAa,OAAA;EAqjBZ;;AAAiB;EA9iBlB,SAAA,CAAA;EA6mBU;;;EAtmBV,UAAA,CAAW,KAAA;EAsmBwB;;;EA/lBnC,QAAA,CAAA;EA+lBoD;;;EAxlBpD,KAAA,CAAA;;;;EAOA,UAAA,CAAA;;;;EAOA,SAAA,CAAA;;;;EAOA,MAAA,CAAA;;;;EAOA,UAAA,CAAA;;;;EAOA,OAAA,CAAA;;;;EAOA,SAAA,CAAA;;;;EAOA,MAAA,CAAA;;;;EAOA,MAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqCA,IAAA,CAAK,UAAA;;;;MAWD,cAAA,CAAA;;;;;;;;;;;;;EAoBJ,EAAA,CAAG,GAAA,EAAK,GAAA;;;;;;;;;;;;;EA4BR,EAAA,CAAG,IAAA;;;;;;;;;;EAiBH,OAAA,CAAQ,IAAA,EAAM,QAAA;;;;;;;;;;;EAoCd,KAAA,CAAM,IAAA,EAAM,QAAA;;;;;;;;;;;;EAwCZ,UAAA,CAAW,EAAA;;;;;;;;;;EAmBX,cAAA,CAAe,IAAA;;;;;;;;;;;;;;;EAmBf,KAAA,CAAM,UAAA,UAAoB,KAAA,WAAc,iBAAA;;;;EAkCxC,SAAA,CAAA;;;;;EAaA,OAAA,CAAA;;;;;;EASA,KAAA,CAAA;;;;;;;;;;EAaA,SAAA,CAAA;;;;;;;;;EAgBM,GAAA,CAAA,GAAO,OAAA,CAAQ,SAAA;;;;;;;;;EAgDrB,iBAAA,CAAA,GAAqB,OAAA;;;;UAiBpB,IAAA;;;;UAOM,iBAAA;;;;UA0BN,oBAAA;;;;UAeA,MAAA;;;;;;;;;UAYA,iBAAA;;;;;;;;;;;;;;;;UA4CA,iBAAA;AAAA;;;;;;;;;;;;;;;iBA+DM,GAAA,CAAI,IAAA,UAAc,QAAA,EAAU,WAAA,GAAc,GAAG"}