@stacksjs/scheduler 0.58.72 → 0.59.1

package/README.md

@@ -127,7 +127,6 @@ For casual chit-chat with others using this package:
 Many thanks to the following core technologies & people who have contributed to this package:
 
 - [Chris Breuer](https://github.com/chrisbbreuer)
-- [Novu](https://novu.co/)
 - [All Contributors](../../contributors)
 
 ## 📄 License

package/dist/constants.d.ts

@@ -0,0 +1,74 @@
+export declare const CONSTRAINTS: Readonly<{
+    readonly second: readonly [0, 59];
+    readonly minute: readonly [0, 59];
+    readonly hour: readonly [0, 23];
+    readonly dayOfMonth: readonly [1, 31];
+    readonly month: readonly [1, 12];
+    readonly dayOfWeek: readonly [0, 7];
+}>;
+export declare const MONTH_CONSTRAINTS: Readonly<{
+    readonly 1: 31;
+    readonly 2: 29;
+    readonly 3: 31;
+    readonly 4: 30;
+    readonly 5: 31;
+    readonly 6: 30;
+    readonly 7: 31;
+    readonly 8: 31;
+    readonly 9: 30;
+    readonly 10: 31;
+    readonly 11: 30;
+    readonly 12: 31;
+}>;
+export declare const PARSE_DEFAULTS: Readonly<{
+    readonly second: "0";
+    readonly minute: "*";
+    readonly hour: "*";
+    readonly dayOfMonth: "*";
+    readonly month: "*";
+    readonly dayOfWeek: "*";
+}>;
+export declare const ALIASES: Readonly<{
+    readonly jan: 1;
+    readonly feb: 2;
+    readonly mar: 3;
+    readonly apr: 4;
+    readonly may: 5;
+    readonly jun: 6;
+    readonly jul: 7;
+    readonly aug: 8;
+    readonly sep: 9;
+    readonly oct: 10;
+    readonly nov: 11;
+    readonly dec: 12;
+    readonly sun: 0;
+    readonly mon: 1;
+    readonly tue: 2;
+    readonly wed: 3;
+    readonly thu: 4;
+    readonly fri: 5;
+    readonly sat: 6;
+}>;
+export declare const TIME_UNITS_MAP: Readonly<{
+    readonly SECOND: "second";
+    readonly MINUTE: "minute";
+    readonly HOUR: "hour";
+    readonly DAY_OF_MONTH: "dayOfMonth";
+    readonly MONTH: "month";
+    readonly DAY_OF_WEEK: "dayOfWeek";
+}>;
+export declare const TIME_UNITS: ["second", "minute", "hour", "dayOfMonth", "month", "dayOfWeek"];
+export declare const TIME_UNITS_LEN: number;
+export declare const PRESETS: Readonly<{
+    readonly '@yearly': "0 0 0 1 1 *";
+    readonly '@monthly': "0 0 0 1 * *";
+    readonly '@weekly': "0 0 0 * * 0";
+    readonly '@daily': "0 0 0 * * *";
+    readonly '@hourly': "0 0 * * * *";
+    readonly '@minutely': "0 * * * * *";
+    readonly '@secondly': "* * * * * *";
+    readonly '@weekdays': "0 0 0 * * 1-5";
+    readonly '@weekends': "0 0 0 * * 0,6";
+}>;
+export declare const RE_WILDCARDS: RegExp;
+export declare const RE_RANGE: RegExp;

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class CronError extends Error {
+}
+export declare class ExclusiveParametersError extends CronError {
+    constructor(param1: string, param2: string);
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+import { Schedule } from './schedule';
+export { CronJob as BunCronJob } from './job';
+export { CronTime } from './time';
+export type { CronCallback, CronCommand, CronContext, CronJobParams, CronOnCompleteCallback, CronOnCompleteCommand, Ranges, TimeUnit, } from './types/cron';
+export * from './types/utils';
+export * from './schedule';
+export default Schedule;

package/dist/index.js

@@ -573,6 +573,14 @@ class Schedule {
     new CronJob(this.cronPattern, this.task, null, true, this.timezone);
     log.info(`Scheduled task with pattern: ${this.cronPattern} in timezone: ${this.timezone}`);
   }
+  job(path) {
+    log.info(`Scheduling job: ${path}`);
+    return this;
+  }
+  action(path) {
+    log.info(`Scheduling action: ${path}`);
+    return this;
+  }
   static command(cmd) {
     this.cmd = cmd;
     return this;

package/dist/job.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Many thanks to https://github.com/kelektiv/node-cron for the inspiration
+ */
+import { CronTime } from './time';
+import type { CronCallback, CronContext, CronJobParams, CronOnCompleteCallback, CronOnCompleteCommand, WithOnComplete } from './types/cron';
+export declare class CronJob<OC extends CronOnCompleteCommand | null = null, C = null> {
+    cronTime: CronTime;
+    running: boolean;
+    unrefTimeout: boolean;
+    lastExecution: Date | null;
+    runOnce: boolean;
+    context: CronContext<C>;
+    onComplete?: WithOnComplete<OC> extends true ? CronOnCompleteCallback : undefined;
+    private _timeout?;
+    private _callbacks;
+    private _errorHandler?;
+    constructor(cronTime: CronJobParams<OC, C>['cronTime'], onTick: CronJobParams<OC, C>['onTick'], onComplete?: CronJobParams<OC, C>['onComplete'], start?: CronJobParams<OC, C>['start'], timeZone?: CronJobParams<OC, C>['timeZone'], context?: CronJobParams<OC, C>['context'], runOnInit?: CronJobParams<OC, C>['runOnInit'], utcOffset?: null, unrefTimeout?: CronJobParams<OC, C>['unrefTimeout'], errorHandler?: (error: Error) => void);
+    constructor(cronTime: CronJobParams<OC, C>['cronTime'], onTick: CronJobParams<OC, C>['onTick'], onComplete?: CronJobParams<OC, C>['onComplete'], start?: CronJobParams<OC, C>['start'], timeZone?: null, context?: CronJobParams<OC, C>['context'], runOnInit?: CronJobParams<OC, C>['runOnInit'], utcOffset?: CronJobParams<OC, C>['utcOffset'], unrefTimeout?: CronJobParams<OC, C>['unrefTimeout'], errorHandler?: (error: Error) => void);
+    static from<OC extends CronOnCompleteCommand | null = null, C = null>(params: CronJobParams<OC, C>): CronJob<OC, C>;
+    private _fnWrap;
+    addCallback(callback: CronCallback<C, WithOnComplete<OC>>): void;
+    setTime(time: CronTime): void;
+    nextDate(): import("luxon").DateTime<boolean>;
+    fireOnTick(): void;
+    nextDates(i?: number): import("luxon").DateTime<boolean>[];
+    start(): void;
+    lastDate(): Date | null;
+    /**
+     * Stop the cronjob.
+     */
+    stop(): void;
+}

package/dist/schedule.d.ts

@@ -0,0 +1,29 @@
+import type { DateTime } from 'luxon';
+export declare class Schedule {
+    private cronPattern;
+    private timezone;
+    private readonly task;
+    constructor(task: () => void);
+    everySecond(): this;
+    everyMinute(): this;
+    everyTwoMinutes(): this;
+    everyFiveMinutes(): this;
+    everyTenMinutes(): this;
+    everyThirtyMinutes(): this;
+    hourly(): this;
+    daily(): this;
+    weekly(): this;
+    monthly(): this;
+    yearly(): this;
+    onDays(days: number[]): this;
+    at(time: string): this;
+    setTimeZone(timezone: string): this;
+    start(): void;
+    job(path: string): this;
+    action(path: string): this;
+    static command(cmd: string): typeof Schedule;
+}
+export declare function sendAt(cronTime: string | Date | DateTime): DateTime;
+export declare function timeout(cronTime: string | Date | DateTime): number;
+export type Scheduler = typeof Schedule;
+export default Schedule;

package/dist/time.d.ts

@@ -0,0 +1,159 @@
+import type { Zone } from 'luxon';
+import { DateTime } from 'luxon';
+import type { CronJobParams } from './types/cron';
+export declare class CronTime {
+    source: string | DateTime;
+    timeZone?: string;
+    utcOffset?: number;
+    realDate: boolean;
+    private second;
+    private minute;
+    private hour;
+    private dayOfMonth;
+    private month;
+    private dayOfWeek;
+    constructor(source: CronJobParams['cronTime'], timeZone?: CronJobParams['timeZone'], utcOffset?: null);
+    constructor(source: CronJobParams['cronTime'], timeZone?: null, utcOffset?: CronJobParams['utcOffset']);
+    private _getWeekDay;
+    /**
+     * Ensure that the syntax parsed correctly and correct the specified values if needed.
+     */
+    private _verifyParse;
+    /**
+     * Calculate the "next" scheduled time
+     */
+    sendAt(): DateTime;
+    sendAt(i: number): DateTime[];
+    /**
+     * Get the number of milliseconds in the future at which to fire our callbacks.
+     */
+    getTimeout(): number;
+    /**
+     * writes out a cron string
+     */
+    toString(): string;
+    /**
+     * Json representation of the parsed cron syntax.
+     */
+    toJSON(): string[];
+    /**
+     * Get next date matching the specified cron time.
+     *
+     * Algorithm:
+     * - Start with a start date and a parsed crontime.
+     * - Loop until 5 seconds have passed, or we found the next date.
+     * - Within the loop:
+     *   - If it took longer than 5 seconds to select a date, throw an exception.
+     *   - Find the next month to run at.
+     *   - Find the next day of the month to run at.
+     *   - Find the next day of the week to run at.
+     *   - Find the next hour to run at.
+     *   - Find the next minute to run at.
+     *   - Find the next second to run at.
+     *   - Check that the chosen time does not equal the current execution.
+     * - Return the selected date object.
+     */
+    getNextDateFrom(start: Date | DateTime, timeZone?: string | Zone): DateTime<boolean>;
+    /**
+     * Search backwards in time 1 minute at a time, to detect a DST forward jump.
+     * When the jump is found, the range of the jump is investigated to check for acceptable cron times.
+     *
+     * A pair is returned, whose first is a boolean representing if an acceptable time was found inside the jump,
+     * and whose second is a DateTime representing the first millisecond after the jump.
+     *
+     * The input date is expected to be decently close to a DST jump.
+     * Up to a day in the past is checked before an error is thrown.
+     * @param date
+     * @return [boolean, DateTime]
+     */
+    private _findPreviousDSTJump;
+    /**
+     * Given 2 DateTimes, which represent 1 second before and immediately after a DST forward jump,
+     * checks if a time in the skipped range would have been a valid CronJob time.
+     *
+     * Could technically work with just one of these values, extracting the other by adding or subtracting seconds.
+     * However, this couples the input DateTime to actually being tied to a DST jump,
+     * which would make the function harder to test.
+     * This way the logic just tests a range of minutes and hours, regardless if there are skipped time points underneath.
+     *
+     * Assumes the DST jump started no earlier than 0:00 and jumped forward by at least 1 minute, to at most 23:59.
+     * i.e. The day is assumed constant, but the jump is not assumed to be an hour long.
+     * Empirically, it is almost always one hour, but very, very rarely 30 minutes.
+     *
+     * Assumes dayOfWeek, dayOfMonth and month match all match, so only the hours, minutes and seconds are to be checked.
+     * @param {DateTime} beforeJumpingPoint
+     * @param {DateTime} afterJumpingPoint
+     * @returns {boolean} True if a valid CronJob time exists within the skipped DST range, false otherwise.
+     */
+    private _checkTimeInSkippedRange;
+    /**
+     * Component of checking if a CronJob time existed in a DateTime range skipped by DST.
+     * This subroutine makes a further assumption that the skipped range is fully contained in one hour,
+     * and that all other larger units are valid for the job.
+     *
+     * for example a jump from 02:00:00 to 02:30:00, but not from 02:00:00 to 03:00:00.
+     * @see _checkTimeInSkippedRange
+     *
+     * This is done by checking if any minute in startMinute - endMinute is valid, excluding endMinute.
+     * For endMinute, there is only a match if the 0th second is a valid time.
+     */
+    private _checkTimeInSkippedRangeSingleHour;
+    /**
+     * Component of checking if a CronJob time existed in a DateTime range skipped by DST.
+     * This subroutine assumes the jump touches at least 2 hours, but the jump does not necessarily fully contain these hours.
+     *
+     * @see _checkTimeInSkippedRange
+     *
+     * This is done by defining the minutes to check for the first and last hour,
+     * and checking all 60 minutes for any hours in between them.
+     *
+     * If any hour x minute combination is a valid time, true is returned.
+     * The endMinute x endHour combination is only checked with the 0th second, since the rest would be out of the range.
+     *
+     * @param startHour {number}
+     * @param startMinute {number}
+     * @param endHour {number}
+     * @param endMinute {number}
+     */
+    private _checkTimeInSkippedRangeMultiHour;
+    /**
+     * Given expected and actual hours and minutes, report if a DST forward jump occurred.
+     *
+     * This is the case when the expected is smaller than the acutal.
+     *
+     * It is not sufficient to check only hours, because some parts of the world apply DST by shifting in minutes.
+     * Better to account for it by checking minutes too, before an Australian of Lord Howe Island call us.
+     * @param expectedHour
+     * @param expectedMinute
+     * @param {DateTime} actualDate
+     */
+    private _forwardDSTJump;
+    /**
+     * wildcard, or all params in array (for to string)
+     */
+    private _wcOrAll;
+    private _hasAll;
+    /**
+     * Parse the cron syntax into something useful for selecting the next execution time.
+     *
+     * Algorithm:
+     * - Replace preset
+     * - Replace aliases in the source.
+     * - Trim string and split for processing.
+     * - Loop over split options (ms -> month):
+     *   - Get the value (or default) in the current position.
+     *   - Parse the value.
+     */
+    private _parse;
+    /**
+     * Parse individual field from the cron syntax provided.
+     *
+     * Algorithm:
+     * - Split field by commas aand check for wildcards to ensure proper user.
+     * - Replace wildcard values with <low>-<high> boundaries.
+     * - Split field by commas and then iterate over ranges inside field.
+     *   - If range matches pattern then map over matches using replace (to parse the range by the regex pattern)
+     *   - Starting with the lower bounds of the range iterate by step up to the upper bounds and toggle the CronTime field value flag on.
+     */
+    private _parseField;
+}

package/dist/types/cron.d.ts

@@ -0,0 +1,50 @@
+/// <reference types="node" />
+import type { SpawnOptions } from 'node:child_process';
+import type { DateTime } from 'luxon';
+import type { CONSTRAINTS, TIME_UNITS_MAP } from '../constants';
+import type { CronJob } from '../job';
+import type { IntRange } from './utils';
+interface BaseCronJobParams<OC extends CronOnCompleteCommand | null = null, C = null> {
+    cronTime: string | Date | DateTime;
+    onTick: CronCommand<C, WithOnComplete<OC>>;
+    onComplete?: OC;
+    start?: boolean | null;
+    context?: C;
+    runOnInit?: boolean | null;
+    unrefTimeout?: boolean | null;
+}
+export type CronJobParams<OC extends CronOnCompleteCommand | null = null, C = null> = BaseCronJobParams<OC, C> & ({
+    timeZone?: string | null;
+    utcOffset?: never;
+} | {
+    timeZone?: never;
+    utcOffset?: number | null;
+});
+export type CronContext<C> = C extends null ? CronJob : NonNullable<C>;
+export type CronCallback<C, WithOnCompleteBool extends boolean = false> = (this: CronContext<C>, onComplete: WithOnCompleteBool extends true ? CronOnCompleteCallback : never) => void | Promise<void>;
+export type CronOnCompleteCallback = () => void | Promise<void>;
+export type CronSystemCommand = string | {
+    command: string;
+    args?: readonly string[] | null;
+    options?: SpawnOptions | null;
+};
+export type CronCommand<C, WithOnCompleteBool extends boolean = false> = CronCallback<C, WithOnCompleteBool> | CronSystemCommand;
+export type CronOnCompleteCommand = CronOnCompleteCallback | CronSystemCommand;
+export type WithOnComplete<OC> = OC extends null ? false : true;
+export type TimeUnit = (typeof TIME_UNITS_MAP)[keyof typeof TIME_UNITS_MAP];
+export type TimeUnitField<T extends TimeUnit> = Partial<Record<Ranges[T], boolean>>;
+export interface Ranges {
+    second: SecondRange;
+    minute: MinuteRange;
+    hour: HourRange;
+    dayOfMonth: DayOfMonthRange;
+    month: MonthRange;
+    dayOfWeek: DayOfWeekRange;
+}
+export type SecondRange = IntRange<(typeof CONSTRAINTS)['second'][0], (typeof CONSTRAINTS)['second'][1]>;
+export type MinuteRange = IntRange<(typeof CONSTRAINTS)['minute'][0], (typeof CONSTRAINTS)['minute'][1]>;
+export type HourRange = IntRange<(typeof CONSTRAINTS)['hour'][0], (typeof CONSTRAINTS)['hour'][1]>;
+export type DayOfMonthRange = IntRange<(typeof CONSTRAINTS)['dayOfMonth'][0], (typeof CONSTRAINTS)['dayOfMonth'][1]>;
+export type MonthRange = IntRange<(typeof CONSTRAINTS)['month'][0], (typeof CONSTRAINTS)['month'][1]>;
+export type DayOfWeekRange = IntRange<(typeof CONSTRAINTS)['dayOfWeek'][0], (typeof CONSTRAINTS)['dayOfWeek'][1]>;
+export {};

package/dist/types/utils.d.ts

@@ -0,0 +1,3 @@
+export type IntRange<F extends number, T extends number> = Exclude<Enumerate<T>, Enumerate<F, false>>;
+type Enumerate<N extends number, WithTail extends boolean = true, Acc extends number[] = []> = Acc['length'] extends N ? WithTail extends true ? [...Acc, Acc['length']][number] : Acc[number] : Enumerate<N, WithTail, [...Acc, Acc['length']]>;
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+import type { Ranges } from './types/cron';
+export declare function getRecordKeys<K extends Ranges[keyof Ranges]>(record: Partial<Record<K, boolean>>): K[];
+export declare function getTimeZoneAndOffset(timeZone?: string | null, utcOffset?: number | null): {
+    timeZone: string;
+    utcOffset: null;
+} | {
+    timeZone: null;
+    utcOffset: number;
+} | {
+    timeZone: null;
+    utcOffset: null;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/scheduler",
   "type": "module",
-  "version": "0.58.72",
+  "version": "0.59.1",
   "description": "The Stacks scheduler.",
   "author": "Chris Breuer",
   "license": "MIT",

package/src/schedule.ts

@@ -98,6 +98,17 @@ export class Schedule {
     log.info(`Scheduled task with pattern: ${this.cronPattern} in timezone: ${this.timezone}`)
   }
 
+  // job and action methods need to be added and they accept a path string param
+  job(path: string) {
+    log.info(`Scheduling job: ${path}`)
+    return this
+  }
+
+  action(path: string) {
+    log.info(`Scheduling action: ${path}`)
+    return this
+  }
+
   static command(cmd: string) {
     // log.info(`Executing command: ${cmd}`)
     this.cmd = cmd
@@ -113,4 +124,6 @@ export function timeout(cronTime: string | Date | DateTime): number {
   return new CronTime(cronTime).getTimeout()
 }
 
+export type Scheduler = typeof Schedule
+
 export default Schedule