Extended serialization for cron fields (#379)

* Refactor the CronField constructor to use a full-fledged CronFieldOptions object instead of a wildcard argument

* Remove nthDayOfWeek from public CronExpressionOptions interface and rely on CronDayOfWeek exposed state

* Add # serialization

* Fix ? serialization

* Change CronFieldOptions rawValue empty to make builder more flexible

Author: harrisiirak

src/CronExpression.ts

@@ -7,7 +7,6 @@ export type CronExpressionOptions = {
   endDate?: Date | string | number | CronDate;
   startDate?: Date | string | number | CronDate;
   tz?: string;
-  nthDayOfWeek?: number;
   expression?: string;
   hashSeed?: string;
   strict?: boolean;
@@ -27,7 +26,6 @@ export class CronExpression {
   #currentDate: CronDate;
   readonly #startDate: CronDate | null;
   readonly #endDate: CronDate | null;
-  readonly #nthDayOfWeek: number;
   readonly #fields: CronFieldCollection;
 
   /**
@@ -42,7 +40,6 @@ export class CronExpression {
     this.#currentDate = new CronDate(options.currentDate, this.#tz);
     this.#startDate = options.startDate ? new CronDate(options.startDate, this.#tz) : null;
     this.#endDate = options.endDate ? new CronDate(options.endDate, this.#tz) : null;
-    this.#nthDayOfWeek = options.nthDayOfWeek || 0;
     this.#fields = fields;
   }
 
@@ -236,9 +233,9 @@ export class CronExpression {
     }
 
     // Check nth day of week if specified
-    if (this.#nthDayOfWeek > 0) {
+    if (this.#fields.dayOfWeek.nthDay > 0) {
       const weekInMonth = Math.ceil(dt.getDate() / 7);
-      if (weekInMonth !== this.#nthDayOfWeek) {
+      if (weekInMonth !== this.#fields.dayOfWeek.nthDay) {
         return false;
       }
     }
@@ -367,7 +364,9 @@ export class CronExpression {
         currentDate.applyDateOperation(dateMathVerb, TimeUnit.Day, this.#fields.hour.values.length);
         continue;
       }
-      if (!(this.#nthDayOfWeek <= 0 || Math.ceil(currentDate.getDate() / 7) === this.#nthDayOfWeek)) {
+      if (
+        !(this.#fields.dayOfWeek.nthDay <= 0 || Math.ceil(currentDate.getDate() / 7) === this.#fields.dayOfWeek.nthDay)
+      ) {
         currentDate.applyDateOperation(dateMathVerb, TimeUnit.Day, this.#fields.hour.values.length);
         continue;
       }

src/CronExpressionParser.ts

@@ -142,14 +142,14 @@ export class CronExpressionParser {
     ) as DayOfWeekRange[];
 
     const fields = new CronFieldCollection({
-      second: new CronSecond(second, ['*', '?'].includes(rawFields.second)),
-      minute: new CronMinute(minute, ['*', '?'].includes(rawFields.minute)),
-      hour: new CronHour(hour, ['*', '?'].includes(rawFields.hour)),
-      dayOfMonth: new CronDayOfMonth(dayOfMonth, ['*', '?'].includes(rawFields.dayOfMonth)),
-      month: new CronMonth(month, ['*', '?'].includes(rawFields.month)),
-      dayOfWeek: new CronDayOfWeek(dayOfWeek, ['*', '?'].includes(rawFields.dayOfWeek)),
+      second: new CronSecond(second, { rawValue: rawFields.second }),
+      minute: new CronMinute(minute, { rawValue: rawFields.minute }),
+      hour: new CronHour(hour, { rawValue: rawFields.hour }),
+      dayOfMonth: new CronDayOfMonth(dayOfMonth, { rawValue: rawFields.dayOfMonth }),
+      month: new CronMonth(month, { rawValue: rawFields.month }),
+      dayOfWeek: new CronDayOfWeek(dayOfWeek, { rawValue: rawFields.dayOfWeek, nthDayOfWeek }),
     });
-    return new CronExpression(fields, { ...options, expression, currentDate, nthDayOfWeek });
+    return new CronExpression(fields, { ...options, expression, currentDate });
   }
 
   /**

src/CronFieldCollection.ts

@@ -308,21 +308,21 @@ export class CronFieldCollection {
 
   /**
    * Handles a single range.
+   * @param {CronField} field - The cron field to stringify
    * @param {FieldRange} range {start: number, end: number, step: number, count: number} The range to handle.
-   * @param {number} min The minimum value for the field.
    * @param {number} max The maximum value for the field.
    * @returns {string | null} The stringified range or null if it cannot be stringified.
    * @private
    */
-  static #handleSingleRange(range: FieldRange, min: number, max: number): string | null {
+  static #handleSingleRange(field: CronField, range: FieldRange, max: number): string | null {
     const step = range.step;
     if (!step) {
       return null;
     }
-    if (step === 1 && range.start === min && range.end && range.end >= max) {
-      return '*';
+    if (step === 1 && range.start === field.min && range.end && range.end >= max) {
+      return field.hasQuestionMarkChar ? '?' : '*';
     }
-    if (step !== 1 && range.start === min && range.end && range.end >= max - step + 1) {
+    if (step !== 1 && range.start === field.min && range.end && range.end >= max - step + 1) {
       return `*/${step}`;
     }
     return null;
@@ -388,18 +388,23 @@ export class CronFieldCollection {
     if (field instanceof CronDayOfMonth) {
       max = this.#month.values.length === 1 ? CronMonth.daysInMonth[this.#month.values[0] - 1] : field.max;
     }
-    const ranges = CronFieldCollection.compactField(values);
 
+    const ranges = CronFieldCollection.compactField(values);
     if (ranges.length === 1) {
-      const singleRangeResult = CronFieldCollection.#handleSingleRange(ranges[0], field.min, max);
+      const singleRangeResult = CronFieldCollection.#handleSingleRange(field, ranges[0], max);
       if (singleRangeResult) {
         return singleRangeResult;
       }
     }
     return ranges
-      .map((range) =>
-        range.count === 1 ? range.start.toString() : CronFieldCollection.#handleMultipleRanges(range, max),
-      )
+      .map((range) => {
+        const value =
+          range.count === 1 ? range.start.toString() : CronFieldCollection.#handleMultipleRanges(range, max);
+        if (field instanceof CronDayOfWeek && field.nthDay > 0) {
+          return `${value}#${field.nthDay}`;
+        }
+        return value;
+      })
       .join(',');
   }
 

src/fields/CronDayOfMonth.ts

@@ -1,4 +1,4 @@
-import { CronField } from './CronField';
+import { CronField, CronFieldOptions } from './CronField';
 import { CronChars, CronMax, CronMin, DayOfMonthRange } from './types';
 
 const MIN_DAY = 1;
@@ -28,11 +28,11 @@ export class CronDayOfMonth extends CronField {
   /**
    * CronDayOfMonth constructor. Initializes the "day of the month" field with the provided values.
    * @param {DayOfMonthRange[]} values - Values for the "day of the month" field
-   * @param {boolean} [wildcard=false] - Whether this field is a wildcard
+   * @param {CronFieldOptions} [options] - Options provided by the parser
    * @throws {Error} if validation fails
    */
-  constructor(values: DayOfMonthRange[], wildcard = false) {
-    super(values, wildcard);
+  constructor(values: DayOfMonthRange[], options?: CronFieldOptions) {
+    super(values, options);
     this.validate();
   }
 

src/fields/CronDayOfWeek.ts

@@ -1,4 +1,4 @@
-import { CronField } from './CronField';
+import { CronField, CronFieldOptions } from './CronField';
 import { CronChars, CronMax, CronMin, DayOfWeekRange } from './types';
 
 const MIN_DAY = 0;
@@ -30,10 +30,10 @@ export class CronDayOfWeek extends CronField {
   /**
    * CronDayOfTheWeek constructor. Initializes the "day of the week" field with the provided values.
    * @param {DayOfWeekRange[]} values - Values for the "day of the week" field
-   * @param {boolean} [wildcard=false] - Whether this field is a wildcard
+   * @param {CronFieldOptions} [options] - Options provided by the parser
    */
-  constructor(values: DayOfWeekRange[], wildcard = false) {
-    super(values, wildcard);
+  constructor(values: DayOfWeekRange[], options?: CronFieldOptions) {
+    super(values, options);
     this.validate();
   }
 
@@ -44,4 +44,13 @@ export class CronDayOfWeek extends CronField {
   get values(): DayOfWeekRange[] {
     return super.values as DayOfWeekRange[];
   }
+
+  /**
+   * Returns the nth day of the week if specified in the cron expression.
+   * This is used for the '#' character in the cron expression.
+   * @returns {number} The nth day of the week (1-5) or 0 if not specified.
+   */
+  get nthDay(): number {
+    return this.options.nthDayOfWeek ?? 0;
+  }
 }

src/fields/CronField.ts

@@ -1,20 +1,43 @@
 import { CronChars, CronConstraints, CronFieldType, CronMax, CronMin } from './types';
 
+/**
+ * Represents the serialized form of a cron field.
+ * @typedef {Object} SerializedCronField
+ * @property {boolean} wildcard - Indicates if the field is a wildcard.
+ * @property {(number|string)[]} values - The values of the field.
+ */
 export type SerializedCronField = {
   wildcard: boolean;
   values: (number | string)[];
 };
 
+/**
+ * Represents the options for a cron field.
+ * @typedef {Object} CronFieldOptions
+ * @property {string} rawValue - The raw value of the field.
+ * @property {boolean} [wildcard] - Indicates if the field is a wildcard.
+ * @property {number} [nthDayOfWeek] - The nth day of the week.
+ */
+export type CronFieldOptions = {
+  rawValue?: string;
+  wildcard?: boolean;
+  nthDayOfWeek?: number;
+};
+
 /**
  * Represents a field within a cron expression.
  * This is a base class and should not be instantiated directly.
  * @class CronField
  */
 export abstract class CronField {
   readonly #hasLastChar: boolean = false;
+  readonly #hasQuestionMarkChar: boolean = false;
+
   readonly #wildcard: boolean = false;
   readonly #values: (number | string)[] = [];
 
+  protected readonly options: CronFieldOptions & { rawValue: string } = { rawValue: '' };
+
   /**
    * Returns the minimum value allowed for this field.
    */
@@ -43,7 +66,7 @@ export abstract class CronField {
    * Returns the regular expression used to validate this field.
    */
   static get validChars(): RegExp {
-    return /^[,*\dH/-]+$/;
+    return /^[?,*\dH/-]+$/;
   }
 
   /**
@@ -56,25 +79,27 @@ export abstract class CronField {
   /**
    * CronField constructor. Initializes the field with the provided values.
    * @param {number[] | string[]} values - Values for this field
-   * @param {boolean} [wildcard=false] - Whether this field is a wildcard
+   * @param {CronFieldOptions} [options] - Options provided by the parser
    * @throws {TypeError} if the constructor is called directly
    * @throws {Error} if validation fails
    */
-  protected constructor(
-    values: (number | string)[],
-    /* istanbul ignore next - we always pass a value */ wildcard = false,
-  ) {
+  protected constructor(values: (number | string)[], options: CronFieldOptions = { rawValue: '' }) {
     if (!Array.isArray(values)) {
       throw new Error(`${this.constructor.name} Validation error, values is not an array`);
     }
     if (!(values.length > 0)) {
       throw new Error(`${this.constructor.name} Validation error, values contains no values`);
     }
+
+    /* istanbul ignore next */
+    this.options = {
+      ...options,
+      rawValue: options.rawValue ?? '',
+    };
     this.#values = values.sort(CronField.sorter);
-    this.#wildcard = wildcard;
-    this.#hasLastChar = values.some((expression: number | string) => {
-      return typeof expression === 'string' && expression.indexOf('L') >= 0;
-    });
+    this.#wildcard = this.options.wildcard !== undefined ? this.options.wildcard : this.#isWildcardValue();
+    this.#hasLastChar = this.options.rawValue.includes('L');
+    this.#hasQuestionMarkChar = this.options.rawValue.includes('?');
   }
 
   /**
@@ -112,6 +137,14 @@ export abstract class CronField {
     return this.#hasLastChar;
   }
 
+  /**
+   * Indicates whether this field has a "question mark" character.
+   * @returns {boolean}
+   */
+  get hasQuestionMarkChar(): boolean {
+    return this.#hasQuestionMarkChar;
+  }
+
   /**
    * Indicates whether this field is a wildcard.
    * @returns {boolean}
@@ -144,7 +177,6 @@ export abstract class CronField {
 
   /**
    * Serializes the field to an object.
-   * @todo This is really only for debugging, should it be removed?
    * @returns {SerializedCronField}
    */
   serialize(): SerializedCronField {
@@ -179,4 +211,19 @@ export abstract class CronField {
       throw new Error(`${this.constructor.name} Validation error, duplicate values found: ${duplicate}`);
     }
   }
+
+  /**
+   * Determines if the field is a wildcard based on the values.
+   * When options.rawValue is not empty, it checks if the raw value is a wildcard, otherwise it checks if all values in the range are included.
+   * @returns {boolean}
+   */
+  #isWildcardValue(): boolean {
+    if (this.options.rawValue.length > 0) {
+      return ['*', '?'].includes(this.options.rawValue);
+    }
+
+    return Array.from({ length: this.max - this.min + 1 }, (_, i) => i + this.min).every((value) =>
+      this.#values.includes(value),
+    );
+  }
 }

src/fields/CronHour.ts

@@ -1,4 +1,4 @@
-import { CronField } from './CronField';
+import { CronField, CronFieldOptions } from './CronField';
 import { CronChars, CronMax, CronMin, HourRange } from './types';
 
 const MIN_HOUR = 0;
@@ -26,10 +26,10 @@ export class CronHour extends CronField {
   /**
    * CronHour constructor. Initializes the "hour" field with the provided values.
    * @param {HourRange[]} values - Values for the "hour" field
-   * @param {boolean} [wildcard=false] - Whether this field is a wildcard
+   * @param {CronFieldOptions} [options] - Options provided by the parser
    */
-  constructor(values: HourRange[], wildcard = false) {
-    super(values, wildcard);
+  constructor(values: HourRange[], options?: CronFieldOptions) {
+    super(values, options);
     this.validate();
   }
 

src/fields/CronMinute.ts

@@ -1,4 +1,4 @@
-import { CronField } from './CronField';
+import { CronField, CronFieldOptions } from './CronField';
 import { CronChars, CronMax, CronMin, SixtyRange } from './types';
 
 const MIN_MINUTE = 0;
@@ -26,10 +26,10 @@ export class CronMinute extends CronField {
   /**
    * CronSecond constructor. Initializes the "second" field with the provided values.
    * @param {SixtyRange[]} values - Values for the "second" field
-   * @param {boolean} [wildcard=false] - Whether this field is a wildcard
+   * @param {CronFieldOptions} [options] - Options provided by the parser
    */
-  constructor(values: SixtyRange[], wildcard = false) {
-    super(values, wildcard);
+  constructor(values: SixtyRange[], options?: CronFieldOptions) {
+    super(values, options);
     this.validate();
   }
 

src/fields/CronMonth.ts

@@ -1,5 +1,5 @@
 import { DAYS_IN_MONTH } from '../CronDate';
-import { CronField } from './CronField';
+import { CronField, CronFieldOptions } from './CronField';
 import { CronChars, CronMax, CronMin, MonthRange } from './types';
 
 const MIN_MONTH = 1;
@@ -31,10 +31,10 @@ export class CronMonth extends CronField {
   /**
    * CronDayOfMonth constructor. Initializes the "day of the month" field with the provided values.
    * @param {MonthRange[]} values - Values for the "day of the month" field
-   * @param {boolean} [wildcard=false] - Whether this field is a wildcard
+   * @param {CronFieldOptions} [options] - Options provided by the parser
    */
-  constructor(values: MonthRange[], wildcard = false) {
-    super(values, wildcard);
+  constructor(values: MonthRange[], options?: CronFieldOptions) {
+    super(values, options);
     this.validate();
   }
 

src/fields/CronSecond.ts

@@ -1,5 +1,5 @@
 import { CronChars, CronMax, CronMin, SixtyRange } from './types';
-import { CronField } from './CronField';
+import { CronField, CronFieldOptions } from './CronField';
 
 const MIN_SECOND = 0;
 const MAX_SECOND = 59;
@@ -24,10 +24,10 @@ export class CronSecond extends CronField {
   /**
    * CronSecond constructor. Initializes the "second" field with the provided values.
    * @param {SixtyRange[]} values - Values for the "second" field
-   * @param {boolean} [wildcard=false] - Whether this field is a wildcard
+   * @param {CronFieldOptions} [options] - Options provided by the parser
    */
-  constructor(values: SixtyRange[], wildcard = false) {
-    super(values, wildcard);
+  constructor(values: SixtyRange[], options?: CronFieldOptions) {
+    super(values, options);
     this.validate();
   }