Hashed values (H) ranges and steps support (#382)

* Add support for hashed (H) ranges and steps in cron expressions

* Update README.md

* Add benchmark cases for hashed syntax

Author: harrisiirak

README.md

@@ -294,7 +294,7 @@ The `CronFieldCollection.from` method accepts either CronField instances or raw
 
 ### Hash support
 
-The library support adding [jitter](https://en.wikipedia.org/wiki/Jitter) to the returned intervals using the `H` special character in a field. When `H` is specified instead of `*`, a random value is used (`H` is replaced by `23`, where 23 is picked randomly, within the valid range of the field).
+The library supports adding [jitter](https://en.wikipedia.org/wiki/Jitter) to the returned intervals using the `H` special character in a field. When `H` is specified instead of `*`, a random value is used (`H` is replaced by `23`, where 23 is picked randomly, within the valid range of the field).
 
 This jitter allows to spread the load when it comes to job scheduling. This feature is inspired by Jenkins's cron syntax.
 
@@ -310,9 +310,18 @@ const interval = CronExpressionParser.parse('30 H * * *');
 // At every minutes of <randomized> hour at <randomized> second everyday.
 const interval = CronExpressionParser.parse('H * H * * *');
 
-// At every 5th minute from <randomized> through 59 everyday.
+// At every 5th minute starting from a random offset.
+// For example, if the random offset is 3, it will run at minutes 3, 8, 13, 18, etc.
 const interval = CronExpressionParser.parse('H/5 * * * *');
 
+// At a random minute within the range 0-10 everyday.
+const interval = CronExpressionParser.parse('H(0-10) * * * *');
+
+// At every 5th minute starting from a random offset within the range 0-4.
+// For example, if the random offset is 2, it will run at minutes 2, 7, 12, 17, etc.
+// The random offset is constrained to be less than the step value.
+const interval = CronExpressionParser.parse('H(0-29)/5 * * * *');
+
 // At every minute of the third <randomized> day of the month
 const interval = CronExpressionParser.parse('* * * * H#3');
 ```

benchmarks/benchmark-inputs.ts

@@ -16,4 +16,10 @@ export const benchmarkInputs: BenchmarkInput[] = [
   { pattern: '0 0 0 * * 4,6L', description: 'At midnight on every Thursday and last Saturday of every month' },
   { pattern: '0 0 0 * * 1L,5L', description: 'At midnight on the last Monday and last Friday of every month' },
   { pattern: '0 0 6-20/2,L 2 *', description: 'At midnight on every 2nd hour between 6-20 and last day in February' },
+  { pattern: '0 H * * *', description: 'Every hour on every day of every month' },
+  { pattern: '0 H/3 * * *', description: 'Every 3 hours on every day of every month' },
+  {
+    pattern: 'H H H(9-20)/3 1-11 *',
+    description: 'Every 3 hours between 9am and 8pm on the 1st through 11th months',
+  },
 ];

src/CronExpressionParser.ts

@@ -205,11 +205,89 @@ export class CronExpressionParser {
       throw new Error(`Invalid characters, got value: ${value}`);
     }
 
-    // Replace '*' and '?'
-    value = value.replace(/[*?]/g, constraints.min + '-' + constraints.max);
-    // Replace 'H' using the seeded PRNG
-    value = value.replace(/H/g, String(Math.floor(rand() * (constraints.max - constraints.min + 1) + constraints.min)));
-    return CronExpressionParser.#parseSequence(field, value, constraints);
+    value = this.#parseWildcard(value, constraints);
+    value = this.#parseHashed(value, constraints, rand);
+    return this.#parseSequence(field, value, constraints);
+  }
+
+  /**
+   * Parse a wildcard from a cron expression.
+   * @param {string} value - The value to parse.
+   * @param {CronConstraints} constraints - The constraints for the field.
+   * @private
+   */
+  static #parseWildcard(value: string, constraints: CronConstraints): string {
+    return value.replace(/[*?]/g, constraints.min + '-' + constraints.max);
+  }
+
+  /**
+   * Parse a hashed value from a cron expression.
+   * @param {string} value - The value to parse.
+   * @param {CronConstraints} constraints - The constraints for the field.
+   * @param {PRNG} rand - The random number generator to use.
+   * @private
+   */
+  static #parseHashed(value: string, constraints: CronConstraints, rand: PRNG): string {
+    const randomValue = rand();
+    return value.replace(/H(?:\((\d+)-(\d+)\))?(?:\/(\d+))?/g, (_, min, max, step) => {
+      // H(range)/step
+      if (min && max && step) {
+        const minNum = parseInt(min, 10);
+        const maxNum = parseInt(max, 10);
+        const stepNum = parseInt(step, 10);
+
+        if (minNum > maxNum) {
+          throw new Error(`Invalid range: ${minNum}-${maxNum}, min > max`);
+        }
+        if (stepNum <= 0) {
+          throw new Error(`Invalid step: ${stepNum}, must be positive`);
+        }
+
+        const minStart = Math.max(minNum, constraints.min);
+        const offset = Math.floor(randomValue * stepNum);
+        const values = [];
+        for (let i = Math.floor(minStart / stepNum) * stepNum + offset; i <= maxNum; i += stepNum) {
+          if (i >= minStart) {
+            values.push(i);
+          }
+        }
+
+        return values.join(',');
+      }
+      // H(range)
+      else if (min && max) {
+        const minNum = parseInt(min, 10);
+        const maxNum = parseInt(max, 10);
+
+        if (minNum > maxNum) {
+          throw new Error(`Invalid range: ${minNum}-${maxNum}, min > max`);
+        }
+        return String(Math.floor(randomValue * (maxNum - minNum + 1)) + minNum);
+      }
+      // H/step
+      else if (step) {
+        const stepNum = parseInt(step, 10);
+
+        // Validate step
+        if (stepNum <= 0) {
+          throw new Error(`Invalid step: ${stepNum}, must be positive`);
+        }
+
+        const offset = Math.floor(randomValue * stepNum);
+        const values = [];
+        for (let i = Math.floor(constraints.min / stepNum) * stepNum + offset; i <= constraints.max; i += stepNum) {
+          if (i >= constraints.min) {
+            values.push(i);
+          }
+        }
+
+        return values.join(',');
+      }
+      // H
+      else {
+        return String(Math.floor(randomValue * (constraints.max - constraints.min + 1) + constraints.min));
+      }
+    });
   }
 
   /**

src/fields/CronDayOfMonth.ts

@@ -23,7 +23,7 @@ export class CronDayOfMonth extends CronField {
     return DAY_CHARS;
   }
   static get validChars(): RegExp {
-    return /^[?,*\dLH/-]+$/;
+    return /^[?,*\dLH/-]+$|^.*H\(\d+-\d+\)\/\d+.*$|^.*H\(\d+-\d+\).*$|^.*H\/\d+.*$/;
   }
   /**
    * CronDayOfMonth constructor. Initializes the "day of the month" field with the provided values.

src/fields/CronDayOfWeek.ts

@@ -24,7 +24,7 @@ export class CronDayOfWeek extends CronField {
   }
 
   static get validChars(): RegExp {
-    return /^[?,*\dLH#/-]+$/;
+    return /^[?,*\dLH#/-]+$|^.*H\(\d+-\d+\)\/\d+.*$|^.*H\(\d+-\d+\).*$|^.*H\/\d+.*$/;
   }
 
   /**

src/fields/CronField.ts

@@ -66,7 +66,7 @@ export abstract class CronField {
    * Returns the regular expression used to validate this field.
    */
   static get validChars(): RegExp {
-    return /^[?,*\dH/-]+$/;
+    return /^[?,*\dH/-]+$|^.*H\(\d+-\d+\)\/\d+.*$|^.*H\(\d+-\d+\).*$|^.*H\/\d+.*$/;
   }
 
   /**

tests/CronExpressionParser.test.ts

@@ -1685,7 +1685,29 @@ describe('CronExpressionParser', () => {
     });
   });
 
-  describe('test expressions using the hash extension syntax', () => {
+  describe('test expressions using hashed extension syntax', () => {
+    describe('pattern validation', () => {
+      // Test invalid step value for H/step pattern
+      test('throws error for invalid step in H/step pattern', () => {
+        expect(() => CronExpressionParser.parse('H/0 * * * *')).toThrow('Invalid step: 0, must be positive');
+      });
+
+      // Test invalid range for H(range) pattern
+      test('throws error for invalid range in H(range) pattern', () => {
+        expect(() => CronExpressionParser.parse('H(10-5) * * * *')).toThrow('Invalid range: 10-5, min > max');
+      });
+
+      // Test invalid range for H(range)/step pattern
+      test('throws error for invalid range in H(range)/step pattern', () => {
+        expect(() => CronExpressionParser.parse('H(10-5)/2 * * * *')).toThrow('Invalid range: 10-5, min > max');
+      });
+
+      // Test invalid step for H(range)/step pattern
+      test('throws error for invalid step in H(range)/step pattern', () => {
+        expect(() => CronExpressionParser.parse('H(1-10)/0 * * * *')).toThrow('Invalid step: 0, must be positive');
+      });
+    });
+
     // Not having a seed is making tests less useful
     describe('without a custom seed', () => {
       test('parses expressions using H on all fields', () => {
@@ -1754,7 +1776,10 @@ describe('CronExpressionParser', () => {
           { expression: '* * * H H *', expected: '* * * 12 8 *' },
           { expression: '* * * * H H', expected: '* * * * 8 0' },
           { expression: 'H H H H H H', expected: '5 34 15 12 8 0' },
-          { expression: 'H/5 * * * * *', expected: '5/5 * * * * *' },
+          { expression: 'H/5 * * * * *', expected: '*/5 * * * * *' },
+          { expression: 'H(10-20) * * * *', expected: '0 16 * * * *' },
+          { expression: 'H(0-29)/10 * * * *', expected: '0 5,15,25 * * * *' },
+          { expression: '* H H(9-20)/3 * * 1-5', expected: '* 34 10-19/3 * * 1-5' },
           { expression: '* * * * * H#1', expected: '* * * * * 0#1' },
         ];