cron-converter-u2q 1.0.1 → 1.1.0

package/README.md

@@ -1,14 +1,23 @@
 # cron-converter-u2q
 
-Easily convert cron expressions between Unix and Quartz formats with the `cron-converter-u2q` package
+Easily work with cron expressions using the `cron-converter-u2q` package. Effortlessly convert between Unix and Quartz formats and describe cron schedules in plain language for better understanding and usability.
 
 ![example event parameter](https://github.com/rahu619/cron-converter-u2q/actions/workflows/integration.yml/badge.svg?branch=main)
-![example event parameter](https://github.com/rahu619/cron-converter-u2q/actions/workflows/release.yml/badge.svg?branch=main)
+![example event parameter](https://github.com/rahu619/cron-converter-u2q/actions/workflows/release.yml/badge.svg?event=workflow_dispatch)
 [![NPM version](https://badge.fury.io/js/cron-converter-u2q.svg)](https://www.npmjs.com/package/cron-converter-u2q)
 
 ### Features
 
-:arrows_counterclockwise: Two-way conversion: from Unix to Quartz and Quartz to Unix.
+:arrows_counterclockwise: **Two-way conversion**
+
+Effortlessly convert cron expressions: 
+- From Unix to Quartz 
+- From Quartz to Unix
+
+:memo: **Human-readable Descriptions**
+
+Translate cron schedules into plain, understandable text: 
+- Example:  `*/5 * * * *` -> "Every 5 minutes"
 
 ### Installation
 
@@ -40,21 +49,51 @@ If you're using ES6 Modules
 import { CronConverterU2QModule as c2q } from "cron-converter-u2q";
 ```
 
-Convert from Unix to Quartz
+### Conversion Methods
+
+#### Convert from Unix to Quartz:
 
 ```javascript
 const quartzExpression = c2q.unixToQuartz("5 * * * *");
 ```
 
-Convert from Quartz to Unix
+#### Convert from Quartz to Unix:
 
 ```javascript
 const unixExpression = c2q.quartzToUnix("* */5 * ? * * *");
 ```
 
+### Description Methods
+
+You can now generate human-readable descriptions for Unix and Quartz cron expressions.
+
+#### Describe Unix Cron Expressions:
+
+```javascript
+const description = c2q.describeUnix("5 * * * *");
+console.log(description); // Outputs: "Every 5 minutes"
+```
+
+#### Describe Quartz Cron Expressions:
+
+```javascript
+const description = c2q.describeQuartz("0 0 8 * * ?");
+console.log(description); // Outputs: "At 8 o'clock"
+```
+
+### Contribution Guide
+1. **Fork the repository.**
+2. **Create a feature branch:** 
+```bash 
+git checkout -b feature/xxxx
+```
+3. **Commit changes:** 
+4. **Push the branch:** 
+5. **Open a Pull Request.**
+
 ### Development Notice
 
-This package is still under active development. Some methods and features might not be stable yet. We're working diligently to improve and stabilize the package. Any feedback, suggestions, or contributions are highly appreciated!
+Any feedback, suggestions, or contributions are highly appreciated!
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cron-converter-u2q",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Converts cron expressions between unix and quartz formats",
   "main": "lib/index.js",
   "types": "types/index.d.ts",

package/src/__tests__/index.test.ts

@@ -1,131 +1,142 @@
-import { CronConverterU2Q as converter, CronDescriberU2Q as describer } from '../index';
+import {
+  CronConverterU2Q as converter,
+  CronDescriberU2Q as describer,
+} from "../index";
 
 //Basic suite of tests
-describe('Unix2Quartz Conversion', () => {
-
-    test('Every minute', () => {
-        const result = converter.unixToQuartz('* * * * *');
-        expect(result).toBe("0 * * ? * *");
-    });
-
-    test('Every 5 minutes', () => {
-        const result = converter.unixToQuartz('*/5 * * * *');
-        expect(result).toBe("0 */5 * ? * *");
-    });
-
-    test('Every hour at minute 30', () => {
-        const result = converter.unixToQuartz('30 * * * *');
-        expect(result).toBe("0 30 * ? * *");
-    });
-
-    test('Everyday at 12pm', () => {
-        const result = converter.unixToQuartz('0 12 * * *');
-        expect(result).toBe("0 0 12 ? * *");
-    });
-
-    test('Every Monday at 12pm', () => {
-        const result = converter.unixToQuartz('0 12 * * 1');
-        expect(result).toBe("0 0 12 ? * 1");
-    });
-
-    test('Every 10th day of the month', () => {
-        const result = converter.unixToQuartz('0 0 10 * *');
-        expect(result).toBe("0 0 0 10 * ?");
-    });
-
-    test('Every January 1st at 12am', () => {
-        const result = converter.unixToQuartz('0 0 1 1 *');
-        expect(result).toBe("0 0 0 1 1 ?");
-    });
-
-    test('Every last day of the month', () => {
-        const result = converter.unixToQuartz('59 23 L * *');
-        expect(result).toBe("0 59 23 L * ?");
-    });
-
-    test('Every day at 2:30 AM', () => {
-        const result = converter.unixToQuartz('30 2 * * *');
-        expect(result).toBe('0 30 2 ? * *');
-    });
-
-    test('Every Monday at 2:30 AM', () => {
-        const result = converter.unixToQuartz('30 2 * * 1');
-        expect(result).toBe('0 30 2 ? * 1');
-    });
-
-    test('Every day at 1:00 AM and 1:00 PM', () => {
-        const result = converter.unixToQuartz('0 1,13 * * *');
-        expect(result).toBe('0 0 1,13 ? * *');
-    });
-
-    test('Every 15 minutes', () => {
-        const result = converter.unixToQuartz('*/15 * * * *');
-        expect(result).toBe('0 */15 * ? * *');
-    });
-
-    //Include
-    // test('Last day of every month at 4:45 PM conversion', () => {
-    //     const result = converter.unixToQuartz('45 16 28-31 * *');
-    //     expect(result).toBe('45 16 L * ?');
-    // });
-
-    // test('Last Sunday of every month at 4:45 PM conversion', () => {
-    //     const result = converter.unixToQuartz('45 16 22-31 * 0');
-    //     expect(result).toBe('45 16 ? * 7L');
-    // });
-
-    // test('Second Wednesday of every month at 1:00 AM conversion', () => {
-    //     const result = converter.quartzToUnix('0 1 ? * 3#2');
-    //     expect(result).toBe('Not directly possible without additional logic');
-    // });
-
-    // test('Every last Friday of the month conversion', () => {
-    //     const result = converter.unixToQuartz('0 0 * * 5'); //Find equivalent unix expression
-    //     expect(result).toBe("0 0 0 ? * 5L");
-    // });
-
+describe("Unix2Quartz Conversion", () => {
+  test("Every minute", () => {
+    const result = converter.unixToQuartz("* * * * *");
+    expect(result).toBe("0 * * ? * *");
+  });
+
+  test("Every 5 minutes", () => {
+    const result = converter.unixToQuartz("*/5 * * * *");
+    expect(result).toBe("0 */5 * ? * *");
+  });
+
+  test("Every hour at minute 30", () => {
+    const result = converter.unixToQuartz("30 * * * *");
+    expect(result).toBe("0 30 * ? * *");
+  });
+
+  test("Everyday at 12pm", () => {
+    const result = converter.unixToQuartz("0 12 * * *");
+    expect(result).toBe("0 0 12 ? * *");
+  });
+
+  test("Every Monday at 12pm", () => {
+    const result = converter.unixToQuartz("0 12 * * 1");
+    expect(result).toBe("0 0 12 ? * 1");
+  });
+
+  test("Every 10th day of the month", () => {
+    const result = converter.unixToQuartz("0 0 10 * *");
+    expect(result).toBe("0 0 0 10 * ?");
+  });
+
+  test("Every January 1st at 12am", () => {
+    const result = converter.unixToQuartz("0 0 1 1 *");
+    expect(result).toBe("0 0 0 1 1 ?");
+  });
+
+  test("Every last day of the month", () => {
+    const result = converter.unixToQuartz("59 23 L * *");
+    expect(result).toBe("0 59 23 L * ?");
+  });
+
+  test("Every day at 2:30 AM", () => {
+    const result = converter.unixToQuartz("30 2 * * *");
+    expect(result).toBe("0 30 2 ? * *");
+  });
+
+  test("Every Monday at 2:30 AM", () => {
+    const result = converter.unixToQuartz("30 2 * * 1");
+    expect(result).toBe("0 30 2 ? * 1");
+  });
+
+  test("Every day at 1:00 AM and 1:00 PM", () => {
+    const result = converter.unixToQuartz("0 1,13 * * *");
+    expect(result).toBe("0 0 1,13 ? * *");
+  });
+
+  test("Every 15 minutes", () => {
+    const result = converter.unixToQuartz("*/15 * * * *");
+    expect(result).toBe("0 */15 * ? * *");
+  });
+
+  //Include
+  // test('Last day of every month at 4:45 PM conversion', () => {
+  //     const result = converter.unixToQuartz('45 16 28-31 * *');
+  //     expect(result).toBe('45 16 L * ?');
+  // });
+
+  // test('Last Sunday of every month at 4:45 PM conversion', () => {
+  //     const result = converter.unixToQuartz('45 16 22-31 * 0');
+  //     expect(result).toBe('45 16 ? * 7L');
+  // });
+
+  // test('Second Wednesday of every month at 1:00 AM conversion', () => {
+  //     const result = converter.quartzToUnix('0 1 ? * 3#2');
+  //     expect(result).toBe('Not directly possible without additional logic');
+  // });
+
+  // test('Every last Friday of the month conversion', () => {
+  //     const result = converter.unixToQuartz('0 0 * * 5'); //Find equivalent unix expression
+  //     expect(result).toBe("0 0 0 ? * 5L");
+  // });
 });
 
-
-describe('Quartz2Unix Conversion', () => {
-
-    test('Every 5 minutes conversion', () => {
-        const result = converter.quartzToUnix('0 */5 * ? * *');
-        expect(result).toBe("*/5 * * * *");
-    });
-
-    test('Everyday at 12pm conversion', () => {
-        const result = converter.quartzToUnix('0 0 12 ? * *');
-        expect(result).toBe("0 12 * * *");
-    });
-
-    test('Every Monday at 12pm conversion', () => {
-        const result = converter.quartzToUnix('0 0 12 ? * 1');
-        expect(result).toBe("0 12 * * 1");
-    });
-
-    test('Every 10th day of the month conversion', () => {
-        const result = converter.quartzToUnix('0 0 0 10 * ?');
-        expect(result).toBe("0 0 10 * *");
-    });
-
-    test('Every January 1st at 12am conversion', () => {
-        const result = converter.quartzToUnix('0 0 0 1 1 ?');
-        expect(result).toBe("0 0 1 1 *");
-    });
-
-    test('Every last day of the month conversion', () => {
-        const result = converter.quartzToUnix('0 59 23 L * ?');
-        expect(result).toBe("59 23 L * *");
-    });
+describe("Quartz2Unix Conversion", () => {
+  test("Every 5 minutes conversion", () => {
+    const result = converter.quartzToUnix("0 */5 * ? * *");
+    expect(result).toBe("*/5 * * * *");
+  });
+
+  test("Everyday at 12pm conversion", () => {
+    const result = converter.quartzToUnix("0 0 12 ? * *");
+    expect(result).toBe("0 12 * * *");
+  });
+
+  test("Every Monday at 12pm conversion", () => {
+    const result = converter.quartzToUnix("0 0 12 ? * 1");
+    expect(result).toBe("0 12 * * 1");
+  });
+
+  test("Every 10th day of the month conversion", () => {
+    const result = converter.quartzToUnix("0 0 0 10 * ?");
+    expect(result).toBe("0 0 10 * *");
+  });
+
+  test("Every January 1st at 12am conversion", () => {
+    const result = converter.quartzToUnix("0 0 0 1 1 ?");
+    expect(result).toBe("0 0 1 1 *");
+  });
+
+  test("Every last day of the month conversion", () => {
+    const result = converter.quartzToUnix("0 59 23 L * ?");
+    expect(result).toBe("59 23 L * *");
+  });
 });
 
-
-
-// describe('Unix Description', () => {
-
-//     test('Describe every 5 minutes', () => {
-//         const result = describer.describe('*/5 * * * *');
-//         expect(result).toBe("Every 5 minutes");
-//     });
-// });
+describe("Description", () => {
+  test("Describe every 5 minutes (Unix)", () => {
+    const result = describer.describeUnix("*/5 * * * *");
+    expect(result).toBe("Every 5 minutes");
+  });
+
+  test("Describe every 5 minutes (Quartz)", () => {
+    const result = describer.describeQuartz("0 */5 * * * *");
+    expect(result).toBe("Every 5 minutes");
+  });
+
+  test("Describe daily at 8:00 AM (Unix)", () => {
+    const result = describer.describeUnix("0 8 * * *");
+    expect(result).toBe("At 8 o'clock");
+  });
+
+  test("Describe daily at 8:00 AM (Quartz)", () => {
+    const result = describer.describeQuartz("0 0 8 * * *");
+    expect(result).toBe("At 8 o'clock");
+  });
+});

package/src/describer.ts

@@ -1,58 +1,156 @@
-import { ExpressionHelper as helper } from './helper';
+import { ExpressionHelper as helper } from "./helper";
 
 export class CronDescriberU2Q {
+  /**
+   * Generates a human-readable description for a Unix-style cron expression.
+   *
+   * Unix-style cron expressions consist of 5 parts:
+   * - Minute (0-59)
+   * - Hour (0-23)
+   * - Day of Month (1-31)
+   * - Month (1-12)
+   * - Day of Week (0-6, where 0 = Sunday)
+   * @param unixExpression - A string containing the Unix-style cron expression.
+   * @returns A human-readable description or an error message if invalid.
+   */
+  public static describeUnix(unixExpression: string): string {
+    try {
+      const parts = helper.GetExpressionParts(unixExpression);
+      if (parts.length !== 5) {
+        return "Invalid Unix cron expression";
+      }
 
-    public static describe(expression: string): string {
-        const [second, min, hour, dom, month, dow] = helper.GetExpressionParts(expression);
-        return `${this.describeSecond(second)} ${this.describeMinute(min)} ${this.describeHour(hour)} ${this.describeDayOfMonth(dom)} ${this.describeMonth(month)} ${this.describeDayOfWeek(dow)}`.trim();
-    }
+      const [min, hour, dom, month, dow] = parts;
 
-    // #region Standard cron description logic 
+      const descriptions = [
+        this.describeMinute(min, true),
+        this.describeHour(hour),
+        this.describeDayOfMonth(dom),
+        this.describeMonth(month),
+        this.describeDayOfWeek(dow),
+      ];
 
-    private static describeSecond(second: string): string {
-        if (second === '*') return 'Every second';
-        if (second.startsWith('*/')) return `Every ${second.split('/')[1]} seconds`;
-        return `At second ${second}`;
+      return this.combineDescriptions(descriptions);
+    } catch (error) {
+      return "Invalid Unix cron expression";
     }
+  }
 
-    private static describeMinute(min: string): string {
-        if (min === '*') return 'Every minute';
-        if (min.startsWith('*/')) return `Every ${min.split('/')[1]} minutes`;
-        return `At minute ${min}`;
-    }
+  /**
+   * Generates a human-readable description for a Quartz-style cron expression.
+   *
+   * Quartz-style cron expressions consist of 6 parts:
+   * - Second (0-59)
+   * - Minute (0-59)
+   * - Hour (0-23)
+   * - Day of Month (1-31)
+   * - Month (1-12)
+   * - Day of Week (0-6, where 0 = Sunday)
+   * @param quartzExpression - A string containing the Quartz-style cron expression.
+   * @returns A human-readable description or an error message if invalid.
+   */
+  public static describeQuartz(quartzExpression: string): string {
+    try {
+      const parts = helper.GetExpressionParts(quartzExpression);
+      if (parts.length !== 6) {
+        return "Invalid Quartz cron expression";
+      }
 
-    private static describeHour(hour: string): string {
-        if (hour === '*') return 'of every hour';
-        if (hour.startsWith('*/')) return `Every ${hour.split('/')[1]} hours`;
-        return `At ${hour} o'clock`;
-    }
+      const [second, min, hour, dom, month, dow] = parts;
 
-    private static describeDayOfMonth(dom: string): string {
-        if (dom === '*') return 'on every day';
-        return `on the ${this.ordinalSuffix(Number(dom))} of the month`;
-    }
+      const descriptions = [
+        this.describeSecond(second, true),
+        this.describeMinute(min, true),
+        this.describeHour(hour),
+        this.describeDayOfMonth(dom),
+        this.describeMonth(month),
+        this.describeDayOfWeek(dow),
+      ];
 
-    private static describeMonth(month: string): string {
-        if (month === '*') return 'of every month';
-        const months = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
-        return `in ${months[Number(month) - 1]}`;
+      return this.combineDescriptions(descriptions);
+    } catch (error) {
+      return "Invalid Quartz cron expression";
     }
+  }
 
-    private static describeDayOfWeek(dow: string): string {
-        if (dow === '*') return '';
-        const days = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
-        return `on ${days[Number(dow)]}`;
-    }
+  private static describeSecond(second: string, suppressZero = false): string {
+    if (second === "*" || (suppressZero && second === "0")) return ""; // Suppress default
+    if (second.startsWith("*/")) return `Every ${second.split("/")[1]} seconds`;
+    return `At second ${second}`;
+  }
 
-    private static ordinalSuffix(i: number): string {
-        const j = i % 10;
-        const k = i % 100;
-        if (j == 1 && k != 11) return i + "st";
-        if (j == 2 && k != 12) return i + "nd";
-        if (j == 3 && k != 13) return i + "rd";
-        return i + "th";
-    }
+  private static describeMinute(min: string, suppressZero = false): string {
+    if (min === "*" || (suppressZero && min === "0")) return ""; // Suppress default
+    if (min.startsWith("*/")) return `Every ${min.split("/")[1]} minutes`;
+    return `At minute ${min}`;
+  }
+
+  private static describeHour(hour: string): string {
+    if (hour === "*") return ""; // Default behavior
+    if (hour.startsWith("*/")) return `Every ${hour.split("/")[1]} hours`;
+    return `At ${hour} o'clock`;
+  }
+
+  private static describeDayOfMonth(dom: string): string {
+    if (dom === "*") return ""; // Default behavior
+    return `on the ${this.ordinalSuffix(Number(dom))} of the month`;
+  }
+
+  private static describeMonth(month: string): string {
+    if (month === "*") return ""; // Default behavior
+    const months = [
+      "January",
+      "February",
+      "March",
+      "April",
+      "May",
+      "June",
+      "July",
+      "August",
+      "September",
+      "October",
+      "November",
+      "December",
+    ];
+    const monthIndex = Number(month) - 1;
+    return months[monthIndex]
+      ? `in ${months[monthIndex]}`
+      : "Invalid month value";
+  }
+
+  private static describeDayOfWeek(dow: string): string {
+    if (dow === "*") return ""; // Default behavior
+    const days = [
+      "Sunday",
+      "Monday",
+      "Tuesday",
+      "Wednesday",
+      "Thursday",
+      "Friday",
+      "Saturday",
+    ];
+    const dayIndex = Number(dow);
+    return days[dayIndex]
+      ? `on ${days[dayIndex]}`
+      : "Invalid day of week value";
+  }
 
-    //#endregion
+  private static ordinalSuffix(i: number): string {
+    if (i <= 0) return "Invalid day";
+    const j = i % 10;
+    const k = i % 100;
+    if (j === 1 && k !== 11) return i + "st";
+    if (j === 2 && k !== 12) return i + "nd";
+    if (j === 3 && k !== 13) return i + "rd";
+    return i + "th";
+  }
 
-}
+  private static combineDescriptions(descriptions: string[]): string {
+    const filteredDescriptions = descriptions.filter(
+      (part) => part && part !== ""
+    );
+    return filteredDescriptions.length > 0
+      ? filteredDescriptions.join(" ").trim()
+      : "Every moment"; // Default if all parts are wildcards
+  }
+}

package/types/index.d.ts

@@ -2,5 +2,7 @@ declare module 'cron-converter-u2q' {
     export const CronConverterU2QModule: {
         unixToQuartz(unixExpression: string): string;
         quartzToUnix(quartzExpression: string): string;
+        describeUnix(unixExpression: string): string;
+        describeQuartz(quartzExpression: string): string
     }
 }