cron-converter-u2q 1.3.0 → 1.3.2

package/README.md

@@ -1,131 +1,93 @@
 # cron-converter-u2q
 
-[![Github Repo Stars](https://img.shields.io/github/stars/rahu619/cron-converter-u2q?style=social)](https://github.com/rahu619/cron-converter-u2q)
 [![NPM version](https://img.shields.io/npm/v/cron-converter-u2q)](https://www.npmjs.com/package/cron-converter-u2q)
+[![npm downloads](https://img.shields.io/npm/dm/cron-converter-u2q)](https://www.npmjs.com/package/cron-converter-u2q)
 [![GitHub License](https://img.shields.io/github/license/rahu619/cron-converter-u2q?style=plastic)](LICENSE)
 [![GitHub Build](https://github.com/rahu619/cron-converter-u2q/actions/workflows/integration.yml/badge.svg?branch=main)](https://github.com/rahu619/cron-converter-u2q/actions)
-[![Github Release](https://github.com/rahu619/cron-converter-u2q/actions/workflows/release.yml/badge.svg?event=workflow_dispatch)](https://github.com/rahu619/cron-converter-u2q/actions)
-[![Github Top Language](https://img.shields.io/github/languages/top/rahu619/cron-converter-u2q?style=plastic)](https://www.typescriptlang.org/)
-[![npm downloads](https://img.shields.io/npm/dm/cron-converter-u2q)](https://www.npmjs.com/package/cron-converter-u2q)
-
-[![https://nodei.co/npm/cron-converter-u2q.png?downloads=true&downloadRank=true&stars=true](https://nodei.co/npm/cron-converter-u2q.png?downloads=true&downloadRank=true&stars=true)](https://www.npmjs.com/package/cron-converter-u2q)
 
-A powerful TypeScript library for working with cron expressions. Effortlessly convert between Unix and Quartz formats, generate human-readable descriptions, and validate cron expressions with ease.
+A lightweight, zero-dependency TypeScript utility to convert, validate, and describe cron expressions. Seamlessly translate between Unix and Quartz schedules, perform boundary checks, and render human-readable descriptions.
 
-## ✨ Features
+---
 
-### 🔄 Two-way Conversion
-- **Unix to Quartz**: Convert standard Unix cron expressions to Quartz format
-- **Quartz to Unix**: Convert Quartz cron expressions to standard Unix format
-- **Format Validation**: Built-in validation for both formats
-- **Error Handling**: Clear error messages for invalid expressions
+## 💡 Unix vs. Quartz Cron
 
-### 📝 Human-readable Descriptions
-- **Natural Language**: Convert cron expressions to plain English
-- **Multiple Languages**: Support for different language descriptions
-- **Customizable**: Extend with your own description templates
-- **Detailed**: Includes all schedule details (minutes, hours, days, etc.)
+| Specification | Fields | Format | Support |
+| :--- | :--- | :--- | :--- |
+| **Unix Cron** | 5 fields | `min hour dom month dow` | Standard POSIX (Linux, Crontab) |
+| **Quartz Cron** | 6–7 fields | `sec min hour dom month dow [year]` | Java/Spring, AWS EventBridge, Azure |
 
-### 🛠️ Developer Friendly
-- **TypeScript Support**: Full type definitions included
-- **Zero Dependencies**: Lightweight and fast
-- **Well Tested**: Comprehensive test coverage
-- **ES6 Modules**: Support for both CommonJS and ES6 imports
+> [!NOTE]
+> Quartz cron requires exactly one of `day-of-month` or `day-of-week` to contain `?` (when specifying a constraint on the other field) to prevent scheduling conflicts.
 
-### 🔍 Validation & Error Handling
-- **Format Validation**: Ensures cron expressions are valid
-- **Range Checking**: Validates field values within acceptable ranges
-- **Clear Errors**: Descriptive error messages for debugging
-- **Type Safety**: TypeScript types for better development experience
+---
 
 ## 📦 Installation
 
 ```bash
-# Using npm
 npm install cron-converter-u2q
-
-# Using yarn
+# or
 yarn add cron-converter-u2q
-
-# Using pnpm
+# or
 pnpm add cron-converter-u2q
 ```
 
-## 🚀 Quick Start
-
-```typescript
-import { CronConverterU2Q, CronDescriberU2Q } from 'cron-converter-u2q';
-
-// Convert Unix to Quartz
-const quartzExpression = CronConverterU2Q.unixToQuartz('5 * * * *');
-console.log(quartzExpression); // "0 5 * * * ? *"
-
-// Convert Quartz to Unix
-const unixExpression = CronConverterU2Q.quartzToUnix('0 0 8 * * ?');
-console.log(unixExpression); // "0 8 * * *"
-// Get human-readable description
-const description = CronDescriberU2Q.describeUnix('*/5 * * * *');
-console.log(description); // "Every 5 minutes"
-```
+---
 
-## 📚 Examples
+## 🚀 Usage
 
-### Basic Conversions
+### 1. Two-Way Conversion
+Convert seamlessly between formats. Wildcards and aliases are normalized automatically.
 
 ```typescript
-// Unix to Quartz
-CronConverterU2Q.unixToQuartz('0 12 * * *');     // "0 0 12 * * ? *"
-CronConverterU2Q.unixToQuartz('*/15 * * * *');   // "0 */15 * * * ? *"
-// Quartz to Unix
-CronConverterU2Q.quartzToUnix('0 0 8 * * ?');    // "0 8 * * *"
-CronConverterU2Q.quartzToUnix('0 */5 * * * ?');  // "*/5 * * * *"
-```
+import { CronConverterU2Q } from 'cron-converter-u2q';
 
-### Human-readable Descriptions
+// Unix -> Quartz (adds 0 seconds)
+CronConverterU2Q.unixToQuartz('*/15 * * * *');   // "0 */15 * * * * *"
+CronConverterU2Q.unixToQuartz('0 12 * * 1');     // "0 0 12 ? * 2 *"
 
-```typescript
-// Unix format descriptions
-CronDescriberU2Q.describeUnix('0 12 * * *');     // "At 12 o'clock"
-CronDescriberU2Q.describeUnix('*/15 * * * *');   // "Every 15 minutes"
-
-// Quartz format descriptions
-CronDescriberU2Q.describeQuartz('0 0 8 * * ?');  // "At 8 o'clock"
-CronDescriberU2Q.describeQuartz('0 */5 * * * ?'); // "Every 5 minutes"
+// Quartz -> Unix (drops seconds/year)
+CronConverterU2Q.quartzToUnix('0 0 8 * * ?');    // "0 8 * * *"
+CronConverterU2Q.quartzToUnix('0 */5 * ? * 2');  // "*/5 * * * 1"
 ```
 
-## 🤝 Contributing
+### 2. Validation
+Perform boundary checks, detect syntax errors, and validate range limits.
 
-Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+```typescript
+import { CronValidatorU2Q } from 'cron-converter-u2q';
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+// Validate and throw detailed error messages
+CronValidatorU2Q.validateUnix('60 * * * *');    // Throws: "Value 60 is out of range (0-59) for Minute"
+CronValidatorU2Q.validateQuartz('0 */0 * ? * *'); // Throws: "Invalid step value in Minute: 0"
 
-## 📄 License
+// Boolean check
+CronValidatorU2Q.isValidUnix('*/5 * * * *');    // true
+CronValidatorU2Q.isValidQuartz('0 0 12 * * * *'); // true (both are allowed to be '*' in this package)
+```
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+### 3. Human-Readable Descriptions
+Render cron schedules into clear, natural English. Fully supports lists, ranges, step modifiers, and Quartz special symbols.
 
-## 💬 Support
+```typescript
+import { CronDescriberU2Q } from 'cron-converter-u2q';
 
-- 📧 Email: rahu619@gmail.com
-- 💻 GitHub Issues: [Create an issue](https://github.com/rahu619/cron-converter-u2q/issues)
-- ⭐ Star the repository if you find it useful!
+// Unix
+CronDescriberU2Q.describeUnix('*/15 * * * *');   // "Every 15 minutes"
+CronDescriberU2Q.describeUnix('0 12 1-5 * *');   // "At 12 o'clock from the 1st to the 5th of the month"
 
-## 🙏 Acknowledgments
+// Quartz
+CronDescriberU2Q.describeQuartz('0 0 8,12 ? * 2-6 *'); // "At 8 and 12 o'clock from Monday to Friday"
+CronDescriberU2Q.describeQuartz('0 0 0 L * ?');        // "At 0 o'clock on the last day of the month"
+```
 
-- Thanks to all contributors who have helped shape this project
-- Inspired by the need for a simple, reliable cron expression converter
-- Built with TypeScript for better developer experience
+---
 
-## 📖 Specifications
+## 🤝 Contributing
 
-This library's conversion logic is grounded in the following official specifications:
+Contributions are welcome! Please feel free to open issues or submit Pull Requests.
 
-- **POSIX IEEE Std 1003.1** – Defines the standard Unix cron expression format (5 fields: minute, hour, day-of-month, month, day-of-week).
-  [https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html)
+---
 
-- **Quartz Scheduler** – Defines the extended Quartz cron trigger format (6–7 fields: seconds, minute, hour, day-of-month, month, day-of-week, optional year). Notably, exactly one of `day-of-month` or `day-of-week` must be `?` to avoid scheduling conflicts.
-  [https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html)
+## 📄 License
 
+This project is licensed under the MIT License.

package/lib/converter.d.ts

@@ -4,18 +4,13 @@ export declare class CronConverterU2Q {
      * @param unixExpression - the unix expression
      * @returns the corresponding quartz expression
      */
-    static unixToQuartz(unixExpression: string): string;
+    static unixToQuartz(unixExpression: string, year?: string): string;
     /**
      * Converts a quartz cron expression to a unix cron expression
      * @param quartzExpression - the quartz expression
      * @returns the corresponding unix expression
      */
     static quartzToUnix(quartzExpression: string): string;
-    /**
-     * Converts interval parts for both Unix and Quartz expressions.
-     * In both directions, normalises step notation to the Unix `*\/N` format.
-     */
-    private static convertIntervalParts;
     /**
      * Converts Unix DOW to Quartz DOW, supporting lists, ranges, and special cases.
      * Unix: 0=Sun, 1=Mon, ..., 6=Sat, 7=Sun(alias)

package/lib/converter.js

@@ -9,10 +9,10 @@ class CronConverterU2Q {
      * @param unixExpression - the unix expression
      * @returns the corresponding quartz expression
      */
-    static unixToQuartz(unixExpression) {
+    static unixToQuartz(unixExpression, year = '*') {
         validator_1.CronValidatorU2Q.validateUnix(unixExpression);
         const parts = helper_1.ExpressionHelper.GetExpressionParts(unixExpression);
-        const [min, hour, dom, month, dow] = parts.map(part => this.convertIntervalParts(part));
+        const [min, hour, dom, month, dow] = parts;
         // Enhanced DOW conversion: handle lists, ranges, and special cases
         let quartzDow = this.unixDowToQuartz(dow);
         let quartzDom = dom;
@@ -24,7 +24,14 @@ class CronConverterU2Q {
         else if (dom !== '*' && dow === '*') {
             quartzDow = '?';
         }
-        return `0 ${min} ${hour} ${quartzDom} ${month} ${quartzDow} *`;
+        else if (dom !== '*' && dow !== '*') {
+            throw new Error("Quartz cron does not support specifying both Day of Month and Day of Week");
+        }
+        const result = `0 ${min} ${hour} ${quartzDom} ${month} ${quartzDow} ${year}`;
+        if (year !== '*') {
+            validator_1.CronValidatorU2Q.validateQuartz(result);
+        }
+        return result;
     }
     /**
      * Converts a quartz cron expression to a unix cron expression
@@ -34,7 +41,7 @@ class CronConverterU2Q {
     static quartzToUnix(quartzExpression) {
         validator_1.CronValidatorU2Q.validateQuartz(quartzExpression);
         const parts = helper_1.ExpressionHelper.GetExpressionParts(quartzExpression);
-        const [_, min, hour, dom, month, dow] = parts.map(part => this.convertIntervalParts(part, true));
+        const [_, min, hour, dom, month, dow] = parts.map(part => part.replace(/^0\/(\d+)$/, '*/$1'));
         if (dom.includes('L') || dom.includes('W')) {
             throw new Error("Unix cron does not support 'L' or 'W' in Day of Month");
         }
@@ -46,16 +53,6 @@ class CronConverterU2Q {
         let unixDom = dom === '?' ? '*' : dom;
         return `${min} ${hour} ${unixDom} ${month} ${unixDow}`;
     }
-    /**
-     * Converts interval parts for both Unix and Quartz expressions.
-     * In both directions, normalises step notation to the Unix `*\/N` format.
-     */
-    static convertIntervalParts(part, isQuartz = false) {
-        if (isQuartz) {
-            return part.replace(/^0\/(\d+)$/, '*/$1');
-        }
-        return part;
-    }
     /**
      * Converts Unix DOW to Quartz DOW, supporting lists, ranges, and special cases.
      * Unix: 0=Sun, 1=Mon, ..., 6=Sat, 7=Sun(alias)
@@ -64,8 +61,10 @@ class CronConverterU2Q {
     static unixDowToQuartz(dow) {
         if (dow === '*' || dow === '?')
             return dow;
-        if (dow.includes(','))
-            return dow.split(',').map(d => this.unixDowToQuartz(d)).join(',');
+        if (dow.includes(',')) {
+            const mapped = dow.split(',').map(d => this.unixDowToQuartz(d));
+            return Array.from(new Set(mapped)).join(',');
+        }
         if (dow.includes('-'))
             return dow.split('-').map(d => this.unixDowToQuartz(d)).join('-');
         if (dow.endsWith('L')) {
@@ -92,8 +91,10 @@ class CronConverterU2Q {
         if (dow === '*' || dow === '?')
             return dow === '?' ? '*' : dow;
         // Split compound expressions so each element is converted individually
-        if (dow.includes(','))
-            return dow.split(',').map(d => this.quartzDowToUnix(d)).join(',');
+        if (dow.includes(',')) {
+            const mapped = dow.split(',').map(d => this.quartzDowToUnix(d));
+            return Array.from(new Set(mapped)).join(',');
+        }
         if (dow.includes('-'))
             return dow.split('-').map(d => this.quartzDowToUnix(d)).join('-');
         // Last (L) — convert the numeric day part, preserve L suffix

package/lib/helper.js

@@ -4,10 +4,10 @@ exports.ExpressionHelper = void 0;
 class ExpressionHelper {
     static GetExpressionParts(expression) {
         this.validateIfNullOrEmpty(expression);
-        const parts = expression.split(this.delimiter).map(part => part.trim());
+        const parts = expression.trim().split(/\s+/);
         if (this.quartzExpressionLengths.includes(parts.length))
             return parts;
-        if (this.unixExpressionLength == parts.length)
+        if (this.unixExpressionLength === parts.length)
             return parts;
         throw new Error(`Invalid cron expression!`);
     }

package/package.json

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

package/src/__tests__/index.test.ts

@@ -290,6 +290,49 @@ describe("Converter: error handling", () => {
   test("quartzToUnix throws on 8-field expression", () => {
     expect(() => converter.quartzToUnix("* * * * * * * *")).toThrow();
   });
+
+  test("unixToQuartz throws when both DOM and DOW are specific", () => {
+    expect(() => converter.unixToQuartz("0 0 15 * 1")).toThrow("Quartz cron does not support specifying both Day of Month and Day of Week");
+  });
+});
+
+describe("Converter: deduplication of DOW values", () => {
+  test("unixToQuartz deduplicates redundant DOW values (e.g. 0,7)", () => {
+    expect(converter.unixToQuartz("0 0 * * 0,7")).toBe("0 0 0 ? * 1 *");
+  });
+
+  test("quartzToUnix deduplicates redundant DOW values (e.g. 2,2)", () => {
+    expect(converter.quartzToUnix("0 0 0 ? * 2,2")).toBe("0 0 * * 1");
+  });
+});
+
+describe("ExpressionHelper whitespace robustness", () => {
+  test("handles multiple spaces, tabs, and leading/trailing whitespace correctly", () => {
+    expect(converter.unixToQuartz("  0   12   *   *   *  ")).toBe("0 0 12 * * * *");
+    expect(converter.unixToQuartz("0\t12\t*\t*\t*")).toBe("0 0 12 * * * *");
+  });
+});
+
+describe("Converter: optional year parameter", () => {
+  test("unixToQuartz accepts specific year", () => {
+    expect(converter.unixToQuartz("0 12 * * 1", "2026")).toBe("0 0 12 ? * 2 2026");
+  });
+
+  test("unixToQuartz throws on invalid specific year", () => {
+    expect(() => converter.unixToQuartz("0 12 * * 1", "invalid_year")).toThrow();
+    expect(() => converter.unixToQuartz("0 12 * * 1", "1969")).toThrow(); // out of range
+  });
+
+  test("round-tripping Quartz -> Unix -> Quartz with specific years", () => {
+    const originalQuartz = "0 0 12 ? * 2 2026";
+    const unix = converter.quartzToUnix(originalQuartz); // "0 12 * * 1"
+    
+    const parts = originalQuartz.split(/\s+/);
+    const year = parts.length === 7 ? parts[6] : "*";
+    
+    const reconstructedQuartz = converter.unixToQuartz(unix, year);
+    expect(reconstructedQuartz).toBe(originalQuartz);
+  });
 });
 
 describe("Validator Checks", () => {

package/src/converter.ts

@@ -7,10 +7,10 @@ export class CronConverterU2Q {
      * @param unixExpression - the unix expression
      * @returns the corresponding quartz expression
      */
-    public static unixToQuartz(unixExpression: string): string {
+    public static unixToQuartz(unixExpression: string, year = '*'): string {
         CronValidatorU2Q.validateUnix(unixExpression);
         const parts = helper.GetExpressionParts(unixExpression);
-        const [min, hour, dom, month, dow] = parts.map(part => this.convertIntervalParts(part));
+        const [min, hour, dom, month, dow] = parts;
 
         // Enhanced DOW conversion: handle lists, ranges, and special cases
         let quartzDow = this.unixDowToQuartz(dow);
@@ -22,9 +22,15 @@ export class CronConverterU2Q {
             quartzDom = '?';
         } else if (dom !== '*' && dow === '*') {
             quartzDow = '?';
+        } else if (dom !== '*' && dow !== '*') {
+            throw new Error("Quartz cron does not support specifying both Day of Month and Day of Week");
         }
 
-        return `0 ${min} ${hour} ${quartzDom} ${month} ${quartzDow} *`;
+        const result = `0 ${min} ${hour} ${quartzDom} ${month} ${quartzDow} ${year}`;
+        if (year !== '*') {
+            CronValidatorU2Q.validateQuartz(result);
+        }
+        return result;
     }
 
     /**
@@ -35,7 +41,7 @@ export class CronConverterU2Q {
     public static quartzToUnix(quartzExpression: string): string {
         CronValidatorU2Q.validateQuartz(quartzExpression);
         const parts = helper.GetExpressionParts(quartzExpression);
-        const [_, min, hour, dom, month, dow] = parts.map(part => this.convertIntervalParts(part, true));
+        const [_, min, hour, dom, month, dow] = parts.map(part => part.replace(/^0\/(\d+)$/, '*/$1'));
 
         if (dom.includes('L') || dom.includes('W')) {
             throw new Error("Unix cron does not support 'L' or 'W' in Day of Month");
@@ -51,17 +57,6 @@ export class CronConverterU2Q {
         return `${min} ${hour} ${unixDom} ${month} ${unixDow}`;
     }
 
-    /**
-     * Converts interval parts for both Unix and Quartz expressions.
-     * In both directions, normalises step notation to the Unix `*\/N` format.
-     */
-    private static convertIntervalParts(part: string, isQuartz = false): string {
-        if (isQuartz) {
-            return part.replace(/^0\/(\d+)$/, '*/$1');
-        }
-        return part;
-    }
-
     /**
      * Converts Unix DOW to Quartz DOW, supporting lists, ranges, and special cases.
      * Unix: 0=Sun, 1=Mon, ..., 6=Sat, 7=Sun(alias)
@@ -69,7 +64,10 @@ export class CronConverterU2Q {
      */
     private static unixDowToQuartz(dow: string): string {
         if (dow === '*' || dow === '?') return dow;
-        if (dow.includes(',')) return dow.split(',').map(d => this.unixDowToQuartz(d)).join(',');
+        if (dow.includes(',')) {
+            const mapped = dow.split(',').map(d => this.unixDowToQuartz(d));
+            return Array.from(new Set(mapped)).join(',');
+        }
         if (dow.includes('-')) return dow.split('-').map(d => this.unixDowToQuartz(d)).join('-');
         if (dow.endsWith('L')) {
             const day = dow.slice(0, -1);
@@ -94,7 +92,10 @@ export class CronConverterU2Q {
         if (dow === '*' || dow === '?') return dow === '?' ? '*' : dow;
 
         // Split compound expressions so each element is converted individually
-        if (dow.includes(',')) return dow.split(',').map(d => this.quartzDowToUnix(d)).join(',');
+        if (dow.includes(',')) {
+            const mapped = dow.split(',').map(d => this.quartzDowToUnix(d));
+            return Array.from(new Set(mapped)).join(',');
+        }
         if (dow.includes('-')) return dow.split('-').map(d => this.quartzDowToUnix(d)).join('-');
 
         // Last (L) — convert the numeric day part, preserve L suffix

package/src/helper.ts

@@ -5,9 +5,9 @@ export class ExpressionHelper {
 
     public static GetExpressionParts(expression: string): string[] {
         this.validateIfNullOrEmpty(expression);
-        const parts = expression.split(this.delimiter).map(part => part.trim());
+        const parts = expression.trim().split(/\s+/);
         if (this.quartzExpressionLengths.includes(parts.length)) return parts;
-        if (this.unixExpressionLength == parts.length) return parts;
+        if (this.unixExpressionLength === parts.length) return parts;
 
         throw new Error(`Invalid cron expression!`)
     }

package/types/index.d.ts

@@ -1,6 +1,6 @@
 declare module 'cron-converter-u2q' {
     export class CronConverterU2Q {
-        static unixToQuartz(unixExpression: string): string;
+        static unixToQuartz(unixExpression: string, year?: string): string;
         static quartzToUnix(quartzExpression: string): string;
     }