cronbake/dist/index.d.cts

A powerful and flexible cron job manager built with TypeScript

type CronTime = {
    second?: number[];
    minute?: number[];
    hour?: number[];
    dayOfMonth?: number[];
    month?: number[];
    dayOfWeek?: number[];
};
/**
 * Interface for a cron parser that can parse a cron expression and provide
 * the next and previous execution times.
 */
interface ICronParser {
    /**
     * Parse the cron expression and return a `CronTime` object.
     * @returns A `CronTime` object representing the parsed cron expression.
     */
    parse(): CronTime;
    /**
     * Get the next execution time based on the current time.
     * @returns A `Date` object representing the next execution time.
     */
    getNext(): Date;
    /**
     * Get the previous execution time based on the current time.
     * @returns A `Date` object representing the previous execution time.
     */
    getPrevious(): Date;
}
type unit = 'seconds' | 'minutes' | 'hours' | 'dayOfMonth' | 'months' | 'dayOfWeek';
type day = 'sunday' | 'monday' | 'tuesday' | 'wednesday' | 'thursday' | 'friday' | 'saturday';
type EveryStrType<U extends unit = unit> = `@every_${string}_${U}`;
type AtHourStrType = `@at_${number}:${number}`;
type OnDayStrType<D extends day = day> = `@on_${D}`;
type BetweenStrType = `@between_${number}_${number}`;
type CronExprs = '@every_second' | '@every_minute' | '@yearly' | '@annually' | '@monthly' | '@weekly' | '@daily' | '@hourly' | EveryStrType | AtHourStrType | OnDayStrType | BetweenStrType;
type CronStr = `${string} ${string} ${string} ${string} ${string} ${string}`;
type CronExpression = CronExprs | CronStr;
/**
 * A type that takes a string and returns a `CronExprs` type if the string starts with '@',
 * otherwise returns the input string.
 */
type CronExpressionType<T extends string> = T extends `@${infer U}` ? CronExprs : T;
/**
 * An interface that defines the properties and methods of a cron job.
 * @template T The type of the cron expression.
 */
interface ICron<T extends string = string> {
    /**
     * The name of the cron job.
     */
    name: string;
    /**
     * The cron expression for the job.
     */
    cron: CronExpressionType<T>;
    /**
     * The callback function to execute on each tick of the cron job.
     */
    callback: () => void | Promise<void>;
    /**
     * The function to execute on each tick of the cron job.
     */
    onTick: () => void;
    /**
     * The function to execute when the cron job completes.
     */
    onComplete: () => void;
    /**
     * The function to execute when the cron job encounters an error.
     */
    onError?: (error: Error) => void;
    /**
     * The priority level of the cron job.
     */
    priority: number;
    /**
     * Starts the cron job.
     */
    start: () => void;
    /**
     * Stops the cron job.
     */
    stop: () => void;
    /**
     * Pauses the cron job.
     */
    pause: () => void;
    /**
     * Resumes the cron job.
     */
    resume: () => void;
    /**
     * Destroys the cron job.
     */
    destroy: () => void;
    /**
     * Gets the status of the cron job.
     * @returns The status of the cron job.
     */
    getStatus: () => Status;
    /**
     * Checks if the cron job is running.
     * @returns `true` if the cron job is running, `false` otherwise.
     */
    isRunning: () => boolean;
    /**
     * Gets the date of the last execution of the cron job.
     * @returns The date of the last execution of the cron job.
     */
    lastExecution: () => Date;
    /**
     * Gets the date of the next execution of the cron job.
     * @returns The date of the next execution of the cron job.
     */
    nextExecution: () => Date;
    /**
     * Gets the remaining time until the next execution of the cron job.
     * @returns The remaining time until the next execution of the cron job.
     */
    remaining: () => number;
    /**
     * Gets the time until the next execution of the cron job.
     * @returns The time until the next execution of the cron job.
     */
    time: () => number;
    /**
     * Gets the execution history of the cron job.
     * @returns Array of execution history entries.
     */
    getHistory: () => ExecutionHistory[];
    /**
     * Gets the metrics of the cron job.
     * @returns Job metrics object.
     */
    getMetrics: () => JobMetrics;
    /**
     * Resets the metrics and history of the cron job.
     */
    resetMetrics: () => void;
}
/**
 * A type that defines the options for a cron job.
 * @template T The type of the cron expression.
 */
type CronOptions<T extends string = string> = {
    /**
     * The name of the cron job.
     */
    name: string;
    /**
     * The cron expression for the job.
     * You can use the following formats or you can use a preset
     * @example
     * // wildcards
     * "* * * * * *"
     * // ranges
     * "1-10 * * * * *"
     * // steps
     * "1-10/2 * * * * *" // can be used with wildcards and ranges
     * // lists
     * "1,2,3 * * * * *"
     * // presets
     * "@every_second"
     * "@every_minute"
     * "@yearly"
     * "@annually"
     * "@monthly"
     * "@weekly"
     * "@daily"
     * "@hourly"
     * // custom presets
     * "@every_<number>_<unit>"
     * // where <unit> is one of the following:
     * // "seconds", "minutes", "hours", "dayOfMonth", "months", "dayOfWeek"
     * "@at_<hour>:<minute>"
     * // where <hour> is a number between 0 and 23 and <minute> is a number between 0 and 59
     * "@on_<day>"
     * // where <day> is one of the following:
     * // "sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"
     * "@between_<hour>_<hour>"
     * // where hour is a number between 0 and 23
     */
    cron: CronExpressionType<T>;
    /**
     * The callback function to execute on each tick of the cron job.
     */
    callback: () => void | Promise<void>;
    /**
     * The optional function to execute on each tick of the cron job.
     */
    onTick?: () => void;
    /**
     * The optional function to execute when the cron job completes.
     */
    onComplete?: () => void;
    /**
     * The optional function to execute when the cron job encounters an error.
     */
    onError?: (error: Error) => void;
    /**
     * Whether to start the cron job immediately upon creation.
     */
    start?: boolean;
    /**
     * Priority level for job execution (higher numbers = higher priority)
     */
    priority?: number;
    /**
     * Maximum number of execution history entries to keep
     */
    maxHistory?: number;
    /**
     * Whether to persist this job across restarts
     */
    persist?: boolean;
};
type Status = 'running' | 'stopped' | 'paused' | 'error';
/**
 * Execution history entry for a cron job
 */
type ExecutionHistory = {
    timestamp: Date;
    duration: number;
    success: boolean;
    error?: string;
};
/**
 * Job metrics for monitoring and analysis
 */
type JobMetrics = {
    totalExecutions: number;
    successfulExecutions: number;
    failedExecutions: number;
    averageExecutionTime: number;
    lastExecutionTime?: number;
    lastError?: string;
};
/**
 * Persistence options for cron jobs
 */
type PersistenceOptions = {
    enabled: boolean;
    filePath?: string;
    autoRestore?: boolean;
};
/**
 * Configuration options for the cron scheduler
 */
type SchedulerConfig = {
    pollingInterval?: number;
    useCalculatedTimeouts?: boolean;
    maxHistoryEntries?: number;
};
/**
 * An interface that defines the properties and methods of a baker.
 */
interface IBaker {
    /**
     * Adds a new cron job with the specified options.
     * @returns A new `ICron` object representing the cron job.
     */
    add: (options: CronOptions) => ICron;
    /**
     * Removes the cron job with the specified name.
     */
    remove: (name: string) => void;
    /**
     * Starts the cron job with the specified name.
     */
    bake: (name: string) => void;
    /**
     * Stops baking the cron job with the specified name.
     */
    stop: (name: string) => void;
    /**
     * Pauses the cron job with the specified name.
     */
    pause: (name: string) => void;
    /**
     * Resumes the cron job with the specified name.
     */
    resume: (name: string) => void;
    /**
     * Destroys the cron job with the specified name.
     */
    destroy: (name: string) => void;
    /**
     * Gets the status of the cron job with the specified name.
     * @returns The status of the cron job.
     */
    getStatus: (name: string) => Status;
    /**
     * Checks if the cron job with the specified name is running.
     * @returns `true` if the cron job is running, `false` otherwise.
     */
    isRunning: (name: string) => boolean;
    /**
     * Gets the date of the last execution of the cron job with the specified name.
     * @returns The date of the last execution of the cron job.
     */
    lastExecution: (name: string) => Date;
    /**
     * Gets the date of the next execution of the cron job with the specified name.
     * @returns The date of the next execution of the cron job.
     */
    nextExecution: (name: string) => Date;
    /**
     * Gets the remaining time until the next execution of the cron job with the specified name.
     * @returns The remaining time until the next execution of the cron job.
     */
    remaining: (name: string) => number;
    /**
     * Gets the time until the next execution of the cron job with the specified name.
     * @returns The time until the next execution of the cron job.
     */
    time: (name: string) => number;
    /**
     * Gets the execution history of the cron job with the specified name.
     * @returns Array of execution history entries.
     */
    getHistory: (name: string) => ExecutionHistory[];
    /**
     * Gets the metrics of the cron job with the specified name.
     * @returns Job metrics object.
     */
    getMetrics: (name: string) => JobMetrics;
    /**
     * Gets all cron job names.
     * @returns Array of job names.
     */
    getJobNames: () => string[];
    /**
     * Gets all cron jobs with their status.
     * @returns Map of job names to their cron instances.
     */
    getAllJobs: () => Map<string, ICron>;
    /**
     * Starts all cron jobs.
     */
    bakeAll: () => void;
    /**
     * Stops all cron jobs.
     */
    stopAll: () => void;
    /**
     * Pauses all cron jobs.
     */
    pauseAll: () => void;
    /**
     * Resumes all cron jobs.
     */
    resumeAll: () => void;
    /**
     * Destroys all cron jobs.
     */
    destroyAll: () => void;
    /**
     * Saves the current state of all jobs to persistence storage.
     */
    saveState: () => Promise<void>;
    /**
     * Restores jobs from persistence storage.
     */
    restoreState: () => Promise<void>;
    /**
     * Resets metrics for all jobs.
     */
    resetAllMetrics: () => void;
}
interface IBakerOptions {
    autoStart?: boolean;
    schedulerConfig?: SchedulerConfig;
    persistence?: PersistenceOptions;
    enableMetrics?: boolean;
    onError?: (error: Error, jobName: string) => void;
}

/**
 * A class that implements the `ICron` interface and provides methods manage a cron job.
 */
declare class Cron<T extends string = string> implements ICron<T> {
    name: string;
    cron: CronExpressionType<T>;
    callback: () => void | Promise<void>;
    onTick: () => void;
    onComplete: () => void;
    onError?: (error: Error) => void;
    priority: number;
    private interval;
    private timeout;
    private next;
    private status;
    private parser;
    private history;
    private metrics;
    private maxHistory;
    private useCalculatedTimeouts;
    private pollingInterval;
    /**
     * Creates a new instance of the `Cron` class.
     */
    constructor(options: CronOptions<T>, config?: {
        useCalculatedTimeouts?: boolean;
        pollingInterval?: number;
    });
    /**
     * Validates the cron expression and custom preset bounds
     */
    private validateCronExpression;
    start(): void;
    /**
     * Schedules execution using calculated timeouts for better efficiency
     */
    private scheduleWithTimeout;
    /**
     * Schedules execution using traditional polling interval
     */
    private scheduleWithInterval;
    /**
     * Executes the job and handles metrics/history tracking
     */
    private executeJob;
    stop(): void;
    pause(): void;
    resume(): void;
    /**
     * Clears all active schedulers
     */
    private clearSchedulers;
    destroy(): void;
    getStatus(): Status;
    isRunning(): boolean;
    lastExecution(): Date;
    nextExecution(): Date;
    remaining(): number;
    time(): number;
    getHistory(): ExecutionHistory[];
    getMetrics(): JobMetrics;
    resetMetrics(): void;
    /**
     * Creates a new cron job with the specified options.
     * @returns A new `ICron` object representing the cron job.
     */
    static create<T extends string = string>(options: CronOptions<T>, config?: {
        useCalculatedTimeouts?: boolean;
        pollingInterval?: number;
    }): ICron<T>;
    /**
     * Parses the specified cron expression and returns a `CronTime` object.
     * @returns A `CronTime` object representing the parsed cron expression.
     */
    static parse<T extends string = string>(cron: CronExpressionType<T>): CronTime;
    /**
     * Gets the next execution time for the specified cron expression.
     * @template T The type of the cron expression.
     * @returns A `Date` object representing the next execution time.
     */
    static getNext<T extends string = string>(cron: CronExpressionType<T>): Date;
    /**
     * Gets the previous execution time for the specified cron expression.
     * @returns A `Date` object representing the previous execution time.
     */
    static getPrevious<T extends string = string>(cron: CronExpressionType<T>): Date;
    /**
     * Checks if the specified string is a valid cron expression.
     * @returns `true` if the string is a valid cron expression, `false` otherwise.
     */
    static isValid<T extends string = string>(cron: CronExpressionType<T>): boolean;
}

/**
 * A class that implements the `IBaker` interface and provides methods to manage cron jobs.
 */
declare class Baker implements IBaker {
    private crons;
    private config;
    private persistence;
    private enableMetrics;
    private onError?;
    constructor(options?: IBakerOptions);
    add<T extends string = string>(options: CronOptions<T>): ICron<T>;
    remove(name: string): void;
    bake(name: string): void;
    stop(name: string): void;
    pause(name: string): void;
    resume(name: string): void;
    destroy(name: string): void;
    getStatus(name: string): Status;
    isRunning(name: string): boolean;
    lastExecution(name: string): Date;
    nextExecution(name: string): Date;
    remaining(name: string): number;
    time(name: string): number;
    getHistory(name: string): ExecutionHistory[];
    getMetrics(name: string): JobMetrics;
    getJobNames(): string[];
    getAllJobs(): Map<string, ICron>;
    bakeAll(): void;
    stopAll(): void;
    pauseAll(): void;
    resumeAll(): void;
    destroyAll(): void;
    resetAllMetrics(): void;
    saveState(): Promise<void>;
    restoreState(): Promise<void>;
    /**
     * Creates a new instance of `Baker`.
     */
    static create(options?: IBakerOptions): Baker;
}

/**
 * A class that implements the `ICronParser` interface and provides methods to parse a cron expression
 * and get the next and previous execution times.
 */
declare class CronParser<T extends string> implements ICronParser {
    private cron;
    /**
     * Creates a new instance of the `CronParser` class.
     */
    constructor(cron: CronExpressionType<T>);
    /**
     * A map of cron expression aliases to their corresponding cron expressions.
     */
    private readonly aliases;
    /**
     * Parses a string in the format "@every_<value>_<unit>" and returns the corresponding cron expression.
     */
    private parseEveryStr;
    /**
     * Parses a string in the format "@at_<time>" and returns the corresponding cron expression.
     */
    private parseAtHourStr;
    /**
     * Parses a string in the format "@on_<day>_<unit>" and returns the corresponding cron expression.
     */
    private parseOnDayStr;
    /**
     * Parses a string in the format "@between_<start>_<end>" and returns the corresponding cron expression.
     */
    private parseBetweenStr;
    /**
     * Parses the input string and returns the corresponding cron expression.
     */
    private parseStr;
    /**
     * Parses the cron expression and returns a `CronTime` object representing the parsed cron expression.
     * @returns A `CronTime` object representing the parsed cron expression.
     */
    parse(): CronTime;
    /**
     * Gets the next execution time based on the current time.
     * @returns A `Date` object representing the next execution time.
     */
    getNext(): Date;
    /**
     * Gets the previous execution time based on the current time.
     * @returns A `Date` object representing the previous execution time.
     */
    getPrevious(): Date;
    /**
     * Parses a cron time string and returns an array of numbers representing the valid values for that field.
     */
    private parseCronTime;
    /**
     * Gets the step value for a cron time string.
     */
    private getStep;
    /**
     * Checks if the given date matches the cron time.
     */
    private checkCronTime;
}

export { type AtHourStrType, Baker, type BetweenStrType, Cron, type CronExpression, type CronExpressionType, type CronExprs, type CronOptions, CronParser, type CronTime, type EveryStrType, type IBaker, type IBakerOptions, type ICron, type ICronParser, type OnDayStrType, type Status, type day, Baker as default, type unit };