croner 8.1.2 → 9.0.0-dev.0

package/dist/croner.d.cts

@@ -0,0 +1,487 @@
+declare module "helpers/minitz" {
+    interface TimePoint {
+        y: number;
+        m: number;
+        d: number;
+        h: number;
+        i: number;
+        s: number;
+        tz: string;
+    }
+    /**
+     * Converts a date/time from a specific timezone to a normal date object using the system local time
+     *
+     * Shortcut for minitz.fromTZ(minitz.tp(...));
+     *
+     * @constructor
+     *
+     * @param {Number} y - 1970--
+     * @param {Number} m - 1-12
+     * @param {Number} d - 1-31
+     * @param {Number} h - 0-24
+     * @param {Number} i - 0-60 Minute
+     * @param {Number} s - 0-60
+     * @param {string} tz - Time zone in IANA database format 'Europe/Stockholm'
+     * @param {boolean} [throwOnInvalid] - Default is to return the adjusted time if the call happens during a Daylight-Saving-Time switch.
+     * 										E.g. Value "01:01:01" is returned if input time is 00:01:01 while one hour got actually
+     * 										skipped, going from 23:59:59 to 01:00:00. Setting this flag makes the library throw an exception instead.
+     * @returns {date} - Normal date object with correct UTC and system local time
+     */
+    function minitz(y: number, m: number, d: number, h: number, i: number, s: number, tz: string, throwOnInvalid?: boolean): Date;
+    namespace minitz {
+        var fromTZISO: (localTimeStr: string, tz: string, throwOnInvalid?: boolean) => Date;
+        var fromTZ: (tp: TimePoint, throwOnInvalid?: boolean) => Date;
+        var toTZ: (d: Date, tzStr: string) => {
+            y: number;
+            m: number;
+            d: number;
+            h: number;
+            i: number;
+            s: number;
+            tz: string;
+        };
+        var tp: (y: number, m: number, d: number, h: number, i: number, s: number, tz: string) => {
+            y: number;
+            m: number;
+            d: number;
+            h: number;
+            i: number;
+            s: number;
+            tz: string;
+        };
+        var minitz: typeof import("helpers/minitz").default;
+    }
+    export default minitz;
+    export { minitz };
+}
+declare module "options" {
+    import { CronDate } from "date";
+    import type { Cron } from "croner";
+    type CatchCallbackFn = (e: unknown, job: Cron) => void;
+    type ProtectCallbackFn = (job: Cron) => void;
+    interface CronOptions {
+        name?: string;
+        paused?: boolean;
+        kill?: boolean;
+        catch?: boolean | CatchCallbackFn;
+        unref?: boolean;
+        maxRuns?: number;
+        interval?: number;
+        protect?: boolean | ProtectCallbackFn;
+        startAt?: string | Date | CronDate;
+        stopAt?: string | Date | CronDate;
+        timezone?: string;
+        utcOffset?: number;
+        legacyMode?: boolean;
+        context?: unknown;
+    }
+    function CronOptions(options?: CronOptions): CronOptions;
+    export { CronOptions };
+}
+declare module "pattern" {
+    /**
+     * Constants to represent different occurrences of a weekday in its month.
+     * - `LAST_OCCURRENCE`: The last occurrence of a weekday.
+     * - `ANY_OCCURRENCE`: Combines all individual weekday occurrence bitmasks, including the last.
+     * - `OCCURRENCE_BITMASKS`: An array of bitmasks, with each index representing the respective occurrence of a weekday (0-indexed).
+     */
+    export const LAST_OCCURRENCE = 32;
+    export const ANY_OCCURRENCE: number;
+    export const OCCURRENCE_BITMASKS: number[];
+    /**
+     * Create a CronPattern instance from pattern string ('* * * * * *')
+     * @constructor
+     * @param {string} pattern - Input pattern
+     * @param {string} timezone - Input timezone, used for '?'-substitution
+     */
+    class CronPattern {
+        pattern: string;
+        timezone?: string;
+        second: number[];
+        minute: number[];
+        hour: number[];
+        day: number[];
+        month: number[];
+        dayOfWeek: number[];
+        lastDayOfMonth: boolean;
+        starDOM: boolean;
+        starDOW: boolean;
+        constructor(pattern: string, timezone?: string);
+        /**
+         * Parse current pattern, will throw on any type of failure
+         * @private
+         */
+        private parse;
+        /**
+         * Convert current part (seconds/minutes etc) to an array of 1 or 0 depending on if the part is about to trigger a run or not.
+         */
+        private partToArray;
+        /**
+         * After converting JAN-DEC, SUN-SAT only 0-9 * , / - are allowed, throw if anything else pops up
+         * @throws On error
+         */
+        private throwAtIllegalCharacters;
+        /**
+         * Nothing but a number left, handle that
+         *
+         * @param conf Current part, expected to be a number, as a string
+         * @param type One of "seconds", "minutes" etc
+         * @param valueIndexOffset -1 for day of month, and month, as they start at 1. 0 for seconds, hours, minutes
+         */
+        private handleNumber;
+        /**
+         * Set a specific value for a specific part of the CronPattern.
+         *
+         * @param part The specific part of the CronPattern, e.g., "second", "minute", etc.
+         * @param index The index to modify.
+         * @param value The value to set, typically 0 or 1, in case of "nth weekday" it will be the weekday number used for further processing
+         */
+        private setPart;
+        /**
+         * Take care of ranges with stepping (e.g. 3-23/5)
+         *
+         * @param conf Current part, expected to be a string like 3-23/5
+         * @param type One of "seconds", "minutes" etc
+         * @param valueIndexOffset -1 for day of month, and month, as they start at 1. 0 for seconds, hours, minutes
+         */
+        private handleRangeWithStepping;
+        private extractNth;
+        /**
+         * Take care of ranges (e.g. 1-20)
+         *
+         * @param conf - Current part, expected to be a string like 1-20, can contain L for last
+         * @param type - One of "seconds", "minutes" etc
+         * @param valueIndexOffset - -1 for day of month, and month, as they start at 1. 0 for seconds, hours, minutes
+         */
+        private handleRange;
+        /**
+         * Handle stepping (e.g. * / 14)
+         *
+         * @param conf Current part, expected to be a string like * /20 (without the space)
+         * @param type One of "seconds", "minutes" etc
+         */
+        private handleStepping;
+        /**
+         * Replace day name with day numbers
+         *
+         * @param conf Current part, expected to be a string that might contain sun,mon etc.
+         *
+         * @returns Conf with 0 instead of sun etc.
+         */
+        private replaceAlphaDays;
+        /**
+         * Replace month name with month numbers
+         *
+         * @param conf Current part, expected to be a string that might contain jan,feb etc.
+         *
+         * @returns conf with 0 instead of sun etc.
+         */
+        private replaceAlphaMonths;
+        /**
+         * Replace nicknames with actual cron patterns
+         *
+         * @param pattern Pattern, may contain nicknames, or not
+         *
+         * @returns Pattern, with cron expression insted of nicknames
+         */
+        private handleNicknames;
+        /**
+         * Handle the nth weekday of the month logic using hash sign (e.g. FRI#2 for the second Friday of the month)
+         *
+         * @param index Weekday, example: 5 for friday
+         * @param nthWeekday bitmask, 2 (0x00010) for 2nd friday, 31 (ANY_OCCURRENCE, 0b100000) for any day
+         */
+        private setNthWeekdayOfMonth;
+    }
+    export { CronPattern };
+}
+declare module "date" {
+    import type { CronOptions as CronOptions } from "options";
+    import { type CronPattern } from "pattern";
+    /**
+     * Converts date to CronDate
+     *
+     * @param d Input date, if using string representation ISO 8001 (2015-11-24T19:40:00) local timezone is expected
+     * @param tz String representation of target timezone in Europe/Stockholm format, or a number representing offset in minutes.
+     */
+    class CronDate {
+        tz: string | number | undefined;
+        /**
+         * Current milliseconds
+         * @type {number}
+         */
+        ms: number;
+        /**
+         * Current second (0-59), in local time or target timezone specified by `this.tz`
+         * @type {number}
+         */
+        second: number;
+        /**
+         * Current minute (0-59), in local time or target timezone specified by `this.tz`
+         * @type {number}
+         */
+        minute: number;
+        /**
+         * Current hour (0-23), in local time or target timezone specified by `this.tz`
+         * @type {number}
+         */
+        hour: number;
+        /**
+         * Current day (1-31), in local time or target timezone specified by `this.tz`
+         * @type {number}
+         */
+        day: number;
+        /**
+         * Current month (1-12), in local time or target timezone specified by `this.tz`
+         * @type {number}
+         */
+        month: number;
+        /**
+         * Current full year, in local time or target timezone specified by `this.tz`
+         */
+        year: number;
+        constructor(d?: CronDate | Date | string, tz?: string | number);
+        /**
+         * Check if the given date is the nth occurrence of a weekday in its month.
+         *
+         * @param year The year.
+         * @param month The month (0 for January, 11 for December).
+         * @param day The day of the month.
+         * @param nth The nth occurrence (bitmask).
+         *
+         * @return True if the date is the nth occurrence of its weekday, false otherwise.
+         */
+        private isNthWeekdayOfMonth;
+        /**
+         * Sets internals using a Date
+         */
+        private fromDate;
+        /**
+         * Sets internals by deep copying another CronDate
+         *
+         * @param {CronDate} d - Input date
+         */
+        private fromCronDate;
+        /**
+         * Reset internal parameters (seconds, minutes, hours) if any of them have exceeded (or could have exceeded) their normal ranges
+         *
+         * Will alway return true on february 29th, as that is a date that _could_ be out of bounds
+         */
+        private apply;
+        /**
+         * Sets internals by parsing a string
+         */
+        private fromString;
+        /**
+         * Find next match of current part
+         */
+        private findNext;
+        /**
+         * Increment to next run time recursively
+         *
+         * This function is currently capped at year 3000. Do you have a reason to go further? Open an issue on GitHub!
+         *
+         * @param pattern The pattern used to increment current state
+         * @param options Cron options used for incrementing
+         * @param doing Which part to increment, 0 represent first item of RecursionSteps-array etc.
+         * @return Returns itthis for chaining, or null if increment wasnt possible
+         */
+        private recurse;
+        /**
+         * Increment to next run time
+         *
+         * @param pattern The pattern used to increment current state
+         * @param options Cron options used for incrementing
+         * @param hasPreviousRun If this run should adhere to minimum interval
+         * @return Returns itthis for chaining, or null if increment wasnt possible
+         */
+        increment(pattern: CronPattern, options: CronOptions, hasPreviousRun: boolean): CronDate | null;
+        /**
+         * Convert current state back to a javascript Date()
+         *
+         * @param internal If this is an internal call
+         */
+        getDate(internal?: boolean): Date;
+        /**
+         * Convert current state back to a javascript Date() and return UTC milliseconds
+         */
+        getTime(): number;
+    }
+    export { CronDate };
+}
+declare module "utils" {
+    /**
+     * Helper function to check if a variable is a function
+     * @private
+     *
+     * @param {?} [v] - Variable to check
+     * @returns {boolean}
+     */
+    function isFunction(v: unknown): boolean;
+    /**
+     * Helper function to unref a timer in both Deno and Node
+     * @private
+     * @param {unknown} [timer] - Timer to unref
+     */
+    function unrefTimer(timer: NodeJS.Timeout | number): void;
+    export { isFunction, unrefTimer };
+}
+declare module "croner" {
+    import { CronDate } from "date";
+    import { CronPattern } from "pattern";
+    import { CronOptions } from "options";
+    /**
+     * An array containing all named cron jobs.
+     */
+    const scheduledJobs: Cron[];
+    /**
+     * Encapsulate all internal states in the Cron instance.
+     * Duplicate all options that can change to internal states, for example maxRuns and paused.
+     */
+    type CronState = {
+        kill: boolean;
+        blocking: boolean;
+        /**
+         * Start time of previous trigger, updated after each trigger
+         *
+         * Stored to use as the actual previous run, even while a new trigger
+         * is started. Used by the public funtion `.previousRun()`
+         */
+        previousRun: CronDate | undefined;
+        /**
+         * Start time of current trigger, this is updated just before triggering
+         *
+         * This is used internally as "previous run", as we mostly want to know
+         * when the previous run _started_
+         */
+        currentRun: CronDate | undefined;
+        once: CronDate | undefined;
+        currentTimeout: NodeJS.Timer | number | undefined;
+        maxRuns: number | undefined;
+        paused: boolean | undefined;
+        pattern: CronPattern;
+    };
+    /**
+     * Cron entrypoint
+     *
+     * @constructor
+     * @param pattern - Input pattern, input date, or input ISO 8601 time string
+     * @param [fnOrOptions1] - Options or function to be run each iteration of pattern
+     * @param [fnOrOptions2] - Options or function to be run each iteration of pattern
+     */
+    class Cron {
+        name: string | undefined;
+        options: CronOptions;
+        _states: CronState;
+        fn?: Function;
+        constructor(pattern: string | Date, fnOrOptions1: CronOptions | Function, fnOrOptions2: CronOptions | Function);
+        /**
+         * Find next runtime, based on supplied date. Strips milliseconds.
+         *
+         * @param prev - Date to start from
+         * @returns  Next run time
+         */
+        nextRun(prev?: CronDate | Date | string): Date | null;
+        /**
+         * Find next n runs, based on supplied date. Strips milliseconds.
+         *
+         * @param n - Number of runs to enumerate
+         * @param previous - Date to start from
+         * @returns - Next n run times
+         */
+        nextRuns(n: number, previous: Date | string): Date[];
+        /**
+         * Return the original pattern, if there was one
+         *
+         * @returns Original pattern
+         */
+        getPattern(): string | undefined;
+        /**
+         * Indicates whether or not the cron job is scheduled and running, e.g. awaiting next trigger
+         *
+         * @returns Running or not
+         */
+        isRunning(): boolean;
+        /**
+         * Indicates whether or not the cron job is permanently stopped
+         *
+         * @returns Running or not
+         */
+        isStopped(): boolean;
+        /**
+         * Indicates whether or not the cron job is currently working
+         *
+         * @returns Running or not
+         */
+        isBusy(): boolean;
+        /**
+         * Return current/previous run start time
+         *
+         * @returns Current (if running) or previous run time
+         */
+        currentRun(): Date | null;
+        /**
+         * Return previous run start time
+         *
+         * @returns Previous run time
+         */
+        previousRun(): Date | null;
+        /**
+         * Returns number of milliseconds to next run
+         *
+         * @param prev Starting date, defaults to now - minimum interval
+         */
+        msToNext(prev?: CronDate | Date | string): number | null;
+        /**
+         * Stop execution
+         *
+         * Running this will forcefully stop the job, and prevent furter exection. `.resume()` will not work after stopping.
+         * It will also be removed from the scheduledJobs array if it were named.
+         */
+        stop(): void;
+        /**
+         * Pause execution
+         *
+         * @returns Wether pause was successful
+         */
+        pause(): boolean;
+        /**
+         * Resume execution
+         *
+         * @returns Wether resume was successful
+         */
+        resume(): boolean;
+        /**
+         * Schedule a new job
+         *
+         * @param func - Function to be run each iteration of pattern
+         */
+        schedule(func?: Function): Cron;
+        /**
+         * Internal function to trigger a run, used by both scheduled and manual trigger
+         */
+        private _trigger;
+        /**
+         * Trigger a run manually
+         */
+        trigger(): Promise<void>;
+        /**
+         * Called when it's time to trigger.
+         * Checks if all conditions are currently met,
+         * then instantly triggers the scheduled function.
+         */
+        private _checkTrigger;
+        /**
+         * Internal version of next. Cron needs millseconds internally, hence _next.
+         */
+        private _next;
+        /**
+         * Calculate the previous run if no previous run is supplied, but startAt and interval are set.
+         * This calculation is only necessary if the startAt time is before the current time.
+         * Should only be called from the _next function.
+         */
+        private _calculatePreviousRun;
+    }
+    export default Cron;
+    export { Cron, scheduledJobs };
+}