@warlock.js/scheduler 4.0.47 → 4.0.57

package/cjs/job.d.ts

@@ -0,0 +1,332 @@
+import { type Dayjs } from "dayjs";
+import type { Day, JobIntervals, JobResult, TimeType } from "./types";
+export 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);
+ * ```
+ */
+export declare class Job {
+    readonly name: string;
+    private readonly _callback;
+    /**
+     * Interval configuration for scheduling
+     */
+    private _intervals;
+    /**
+     * Last execution timestamp
+     */
+    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 system timezone)
+     */
+    private _timezone;
+    /**
+     * Cron expression parser (mutually exclusive with interval config)
+     */
+    private _cronParser;
+    /**
+     * Promise resolver for completion waiting
+     */
+    private _completionResolver;
+    /**
+     * 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
+     */
+    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
+     * @param timeType - Type of time unit
+     * @returns this for chaining
+     *
+     * @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
+     * - 'x/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("x/5 * * * *");   // Every 5 minutes
+     * job.cron("0 0 1 * *");     // First day of month at midnight
+     * job.cron("0 x/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
+     *
+     * @param type - Time type (day, month, year)
+     */
+    beginOf(type: TimeType): this;
+    /**
+     * Run task at the end of the specified time period
+     *
+     * @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
+     * @param delay - Delay between retries in milliseconds
+     * @param backoffMultiplier - Optional multiplier for exponential backoff
+     * @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;
+    /**
+     * Determine if the job should run now
+     *
+     * @returns true if the job should execute
+     */
+    shouldRun(): boolean;
+    /**
+     * Execute the job
+     *
+     * @returns Promise resolving to the job result
+     */
+    run(): Promise<JobResult>;
+    /**
+     * Wait for the job to complete
+     * Useful for graceful shutdown
+     *
+     * @returns Promise that resolves when the job completes
+     */
+    waitForCompletion(): Promise<void>;
+    /**
+     * Get current time, respecting timezone if set
+     */
+    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;
+    /**
+     * Calculate the next run time based on interval or cron configuration
+     */
+    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");
+ * ```
+ */
+export declare function job(name: string, callback: JobCallback): Job;
+//# sourceMappingURL=job.d.ts.map

package/cjs/job.d.ts.map

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