@vorsteh-queue/core/dist/utils/scheduler.d.ts

Core queue engine for Vorsteh Queue with TypeScript support, job scheduling, and event system

import { TZDate } from "@date-fns/tz";
/**
 * Parse a cron expression in a timezone and return the next execution time as UTC.
 * This is the core of our UTC-first approach - all timezone calculations happen here,
 * and the result is always a UTC timestamp for storage and processing.
 *
 * @param expression Cron expression (e.g., "0 9 * * *")
 * @param timezone IANA timezone (e.g. `America/New_York`)
 * @param baseDate Base date for calculation (defaults to current time)
 * @returns Next execution time as UTC Date
 *
 * @example
 * ```typescript
 * // 9 AM daily in New York timezone -> returns UTC timestamp
 * const nextRun = parseCron("0 9 * * *", "America/New_York")
 * // Result is always UTC, ready for database storage
 * ```
 */
export declare const parseCron: (expression: string, timezone?: string, baseDate?: Date) => Date;
/**
 * Calculate the next run time for a job - always returns UTC.
 * For cron jobs, timezone conversion happens here and result is UTC.
 * For intervals, timezone is irrelevant (just add milliseconds).
 *
 * @param options Configuration object
 * @returns Next execution time as UTC Date
 *
 * @example
 * ```typescript
 * // Cron: timezone conversion happens here, result is UTC
 * const nextRun = calculateNextRun({
 *   cron: "0 9 * * *",
 *   timezone: "America/New_York",
 *   lastRun: new Date()
 * })
 *
 * // Interval: timezone irrelevant, just add milliseconds
 * const nextRun = calculateNextRun({
 *   repeatEvery: 3600000,
 *   lastRun: new Date()
 * })
 * ```
 */
export declare const calculateNextRun: (options: {
    cron?: string;
    repeatEvery?: number;
    timezone?: string;
    lastRun: Date;
}) => Date;
/**
 * Convert a local date to UTC by interpreting it in a specific timezone.
 * Used when users provide local times that need timezone context.
 *
 * @param date  Input date to convert
 * @param timezone IANA timezone to interpret the date in
 * @returns UTC Date
 *
 * @example
 * ```typescript
 * // User says "run at 9 AM" in New York - convert to UTC for storage
 * const utcDate = toUtcDate(new Date("2024-01-15T09:00:00"), "America/New_York")
 * ```
 */
export declare const toUtcDate: (date: Date, timezone?: string) => Date;
/**
 * Create a UTC Date object.
 *
 * @param input Input date to convert
 * @returns UTC Date
 *
 * @example
 * ```typescript
 * // Create a UTC Date object
 * const utcDate = asUtc(new Date("2024-01-15T09:00:00"))
 * ```
 */
export declare function asUtc(input: Date): TZDate;