cron-converter-u2q 1.2.0 → 1.3.0

package/README.md

@@ -1,100 +1,131 @@
 # cron-converter-u2q
 
-![Github Repo Stars](https://img.shields.io/github/stars/rahu619/cron-converter-u2q?style=social)
+[![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)
-![GitHub License](https://img.shields.io/github/license/rahu619/cron-converter-u2q?style=plastic)
-![GitHub Build](https://github.com/rahu619/cron-converter-u2q/actions/workflows/integration.yml/badge.svg?branch=main)
-![Github Release](https://github.com/rahu619/cron-converter-u2q/actions/workflows/release.yml/badge.svg?event=workflow_dispatch)
-![Github Top Language](https://img.shields.io/github/languages/top/rahu619/cron-converter-u2q?style=plastic)
+[![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)
 
-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.
+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.
 
-### Features
+## ✨ Features
 
-:arrows_counterclockwise: **Two-way conversion**
+### 🔄 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
 
-Effortlessly convert cron expressions: 
-- From Unix to Quartz 
-- From Quartz to Unix
+### 📝 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.)
 
-:memo: **Human-readable Descriptions**
+### 🛠️ 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
 
-Translate cron schedules into plain, understandable text: 
-- Example:  `*/5 * * * *` -> "Every 5 minutes"
+### 🔍 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
-
-Using npm:
+## 📦 Installation
 
 ```bash
+# Using npm
 npm install cron-converter-u2q
-```
-
-Using yarn:
 
-```bash
+# Using yarn
 yarn add cron-converter-u2q
+
+# Using pnpm
+pnpm add cron-converter-u2q
 ```
 
-### Usage
+## 🚀 Quick Start
 
-Firstly, import the CronConverterU2Q module:
+```typescript
+import { CronConverterU2Q, CronDescriberU2Q } from 'cron-converter-u2q';
 
-```javascript
-var cron_converter_u2q = require("cron-converter-u2q");
+// Convert Unix to Quartz
+const quartzExpression = CronConverterU2Q.unixToQuartz('5 * * * *');
+console.log(quartzExpression); // "0 5 * * * ? *"
 
-var c2q = cron_converter_u2q.CronConverterU2Q;
+// 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"
 ```
 
-If you're using ES6 Modules
+## 📚 Examples
 
-```javascript
-import { CronConverterU2QModule as c2q } from "cron-converter-u2q";
+### Basic Conversions
+
+```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 * * * *"
 ```
 
-### Conversion Methods
+### Human-readable Descriptions
 
-#### Convert from Unix to Quartz:
+```typescript
+// Unix format descriptions
+CronDescriberU2Q.describeUnix('0 12 * * *');     // "At 12 o'clock"
+CronDescriberU2Q.describeUnix('*/15 * * * *');   // "Every 15 minutes"
 
-```javascript
-const quartzExpression = c2q.unixToQuartz("5 * * * *");
+// Quartz format descriptions
+CronDescriberU2Q.describeQuartz('0 0 8 * * ?');  // "At 8 o'clock"
+CronDescriberU2Q.describeQuartz('0 */5 * * * ?'); // "Every 5 minutes"
 ```
 
-#### Convert from Quartz to Unix:
+## 🤝 Contributing
 
-```javascript
-const unixExpression = c2q.quartzToUnix("* */5 * ? * * *");
-```
+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.
 
-### Description Methods
+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
 
-You can now generate human-readable descriptions for Unix and Quartz cron expressions.
+## 📄 License
 
-#### Describe Unix Cron Expressions:
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-```javascript
-const description = c2q.describeUnix("5 * * * *");
-console.log(description); // Outputs: "Every 5 minutes"
-```
+## 💬 Support
 
-#### Describe Quartz Cron Expressions:
+- 📧 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!
 
-```javascript
-const description = c2q.describeQuartz("0 0 8 * * ?");
-console.log(description); // Outputs: "At 8 o'clock"
-```
+## 🙏 Acknowledgments
 
-## License
-This project is licensed under the [MIT License](https://opensource.org/license/mit/)
+- 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
-Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
+This library's conversion logic is grounded in the following official specifications:
 
-Please make sure to update tests as appropriate.
+- **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)
 
-### Support
-Any feedback, suggestions, or contributions are highly appreciated!
+- **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)
 

package/lib/converter.d.ts

@@ -1,7 +1,4 @@
 export declare class CronConverterU2Q {
-    static readonly delimiter = " ";
-    static readonly unixExpressionLength = 5;
-    static readonly quartzExpressionLengths: number[];
     /**
      * Converts a unix cron expression to a quartz cron expression by adding '0' seconds
      * @param unixExpression - the unix expression
@@ -14,5 +11,21 @@ export declare class CronConverterU2Q {
      * @returns the corresponding unix expression
      */
     static quartzToUnix(quartzExpression: string): string;
-    private static validateIfNullOrEmpty;
+    /**
+     * 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)
+     * Quartz: 1=Sun, 2=Mon, ..., 7=Sat
+     */
+    private static unixDowToQuartz;
+    /**
+     * Converts Quartz DOW to Unix DOW, supporting lists, ranges, and special cases.
+     * Quartz: 1=Sun, 2=Mon, ..., 7=Sat
+     * Unix: 0=Sun, 1=Mon, ..., 6=Sat
+     */
+    static quartzDowToUnix(dow: string): string;
 }

package/lib/converter.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CronConverterU2Q = void 0;
+const helper_1 = require("./helper");
+const validator_1 = require("./validator");
 class CronConverterU2Q {
     /**
      * Converts a unix cron expression to a quartz cron expression by adding '0' seconds
@@ -8,18 +10,21 @@ class CronConverterU2Q {
      * @returns the corresponding quartz expression
      */
     static unixToQuartz(unixExpression) {
-        this.validateIfNullOrEmpty(unixExpression);
-        const parts = unixExpression.split(this.delimiter);
-        if (parts.length !== this.unixExpressionLength)
-            throw new Error(`Invalid unix cron format`);
-        const [min, hour, dom, month, dow] = parts;
+        validator_1.CronValidatorU2Q.validateUnix(unixExpression);
+        const parts = helper_1.ExpressionHelper.GetExpressionParts(unixExpression);
+        const [min, hour, dom, month, dow] = parts.map(part => this.convertIntervalParts(part));
+        // Enhanced DOW conversion: handle lists, ranges, and special cases
+        let quartzDow = this.unixDowToQuartz(dow);
         let quartzDom = dom;
-        let quartzDow = dow;
-        if (dom === '*' && (dow === '*' || dow !== '*'))
+        // Per Quartz spec, exactly one of DOM or DOW must be '?'
+        // When DOM is '*' and DOW is specific, DOM gets '?'; otherwise DOW gets '?'
+        if (dom === '*' && dow !== '*') {
             quartzDom = '?';
-        else if (dom !== '*' && dow === '*')
+        }
+        else if (dom !== '*' && dow === '*') {
             quartzDow = '?';
-        return `0 ${min} ${hour} ${quartzDom} ${month} ${quartzDow}`;
+        }
+        return `0 ${min} ${hour} ${quartzDom} ${month} ${quartzDow} *`;
     }
     /**
      * Converts a quartz cron expression to a unix cron expression
@@ -27,27 +32,87 @@ class CronConverterU2Q {
      * @returns the corresponding unix expression
      */
     static quartzToUnix(quartzExpression) {
-        this.validateIfNullOrEmpty(quartzExpression);
-        const parts = quartzExpression.split(this.delimiter);
-        if (!this.quartzExpressionLengths.includes(parts.length))
-            throw new Error(`Invalid quartz cron format`);
-        const [_, min, hour, dom, month, dow] = parts;
-        let unixDom = dom;
-        let unixDow = dow;
-        if (dom === '?' && dow === '*')
-            unixDom = '*';
-        else if (dow === '?' && dom === '*')
-            unixDow = '*';
-        else if (dom !== '?' && dom === '?')
-            unixDom = '*';
+        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));
+        if (dom.includes('L') || dom.includes('W')) {
+            throw new Error("Unix cron does not support 'L' or 'W' in Day of Month");
+        }
+        if (dow.includes('L') || dow.includes('#')) {
+            throw new Error("Unix cron does not support 'L' or '#' in Day of Week");
+        }
+        // Enhanced DOW conversion: handle lists, ranges, and special cases
+        let unixDow = this.quartzDowToUnix(dow);
+        let unixDom = dom === '?' ? '*' : dom;
         return `${min} ${hour} ${unixDom} ${month} ${unixDow}`;
     }
-    static validateIfNullOrEmpty(cronExpression) {
-        if (!cronExpression || cronExpression.trim() === '')
-            throw new Error('Empty or null expression');
+    /**
+     * 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)
+     * Quartz: 1=Sun, 2=Mon, ..., 7=Sat
+     */
+    static unixDowToQuartz(dow) {
+        if (dow === '*' || dow === '?')
+            return dow;
+        if (dow.includes(','))
+            return dow.split(',').map(d => this.unixDowToQuartz(d)).join(',');
+        if (dow.includes('-'))
+            return dow.split('-').map(d => this.unixDowToQuartz(d)).join('-');
+        if (dow.endsWith('L')) {
+            const day = dow.slice(0, -1);
+            return `${this.unixDowToQuartz(day)}L`;
+        }
+        if (dow.includes('#')) {
+            const [day, nth] = dow.split('#');
+            return `${this.unixDowToQuartz(day)}#${nth}`;
+        }
+        if (dow === '0' || dow === '7')
+            return '1'; // Sunday
+        const num = parseInt(dow, 10);
+        if (!isNaN(num) && num >= 1 && num <= 6)
+            return (num + 1).toString(); // Mon(1)→2 … Sat(6)→7
+        return dow;
+    }
+    /**
+     * Converts Quartz DOW to Unix DOW, supporting lists, ranges, and special cases.
+     * Quartz: 1=Sun, 2=Mon, ..., 7=Sat
+     * Unix: 0=Sun, 1=Mon, ..., 6=Sat
+     */
+    static quartzDowToUnix(dow) {
+        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('-'))
+            return dow.split('-').map(d => this.quartzDowToUnix(d)).join('-');
+        // Last (L) — convert the numeric day part, preserve L suffix
+        if (dow.endsWith('L')) {
+            const day = dow.slice(0, -1);
+            return `${this.quartzDowToUnix(day)}L`;
+        }
+        // Nth weekday (#) — convert the numeric day part, preserve #N
+        if (dow.includes('#')) {
+            const [day, nth] = dow.split('#');
+            return `${this.quartzDowToUnix(day)}#${nth}`;
+        }
+        // Numeric mapping
+        if (dow === '1')
+            return '0'; // Sunday
+        const num = parseInt(dow, 10);
+        if (!isNaN(num) && num >= 2 && num <= 7)
+            return (num - 1).toString(); // Mon(2)→1 … Sat(7)→6
+        return dow;
     }
 }
 exports.CronConverterU2Q = CronConverterU2Q;
-CronConverterU2Q.delimiter = ' ';
-CronConverterU2Q.unixExpressionLength = 5;
-CronConverterU2Q.quartzExpressionLengths = [6, 7];

package/lib/describer.d.ts

@@ -0,0 +1,41 @@
+export declare 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.
+     */
+    static describeUnix(unixExpression: string): string;
+    /**
+     * Generates a human-readable description for a Quartz-style cron expression.
+     *
+     * Quartz-style cron expressions consist of 6 or 7 parts:
+     * - Second (0-59)
+     * - Minute (0-59)
+     * - Hour (0-23)
+     * - Day of Month (1-31)
+     * - Month (1-12)
+     * - Day of Week (1-7, where 1 = Sunday)
+     * - Year (optional)
+     * @param quartzExpression - A string containing the Quartz-style cron expression.
+     * @returns A human-readable description or an error message if invalid.
+     */
+    static describeQuartz(quartzExpression: string): string;
+    private static describeSecond;
+    private static describeMinute;
+    private static describeHour;
+    private static describeDayOfMonth;
+    private static describeMonth;
+    private static describeDayOfWeek;
+    private static describeYear;
+    private static resolveValue;
+    private static describeField;
+    private static ordinalSuffix;
+    private static combineDescriptions;
+}