From 158fcaa82bf4aea3d4ade00f63cc72d4f414c42b Mon Sep 17 00:00:00 2001
From: Willian Agostini <willian.agostini@gmail.com>
Date: Mon, 24 Feb 2025 11:42:13 -0300
Subject: [PATCH] refactor: rename isCronTimeValid to validateCronExpression
 and update usage examples

---
 README.md                     |  9 ++++++---
 examples/is_crontime_valid.js |  4 ++--
 src/index.ts                  | 11 +----------
 src/time.ts                   | 17 +++++++++++++++++
 tests/crontime.test.ts        | 20 ++++++++++----------
 5 files changed, 36 insertions(+), 25 deletions(-)

diff --git a/README.md b/README.md
index adf8f685..efa49ed6 100644
--- a/README.md
+++ b/README.md
@@ -179,13 +179,16 @@ day of week    0-7 (0 or 7 is Sunday, or use names)
   console.log(`The job would run in ${timeout}ms`);
   ```
 
-- `isCronTimeValid`: Validates if a given cron expression is valid (returns a boolean).
+- `validateCronExpression`: Validates if a given cron expression is valid (returns an object with `valid` and `error` properties).
 
   ```javascript
   import * as cron from 'cron';
 
-  const isValid = cron.isCronTimeValid('0 0 * * *');
-  console.log(`Is the cron expression valid? ${isValid}`);
+  const validation = cron.validateCronExpression('0 0 * * *');
+  console.log(`Is the cron expression valid? ${validation.valid}`);
+  if (!validation.valid) {
+  	console.error(`Validation error: ${validation.error}`);
+  }
   ```
 
 ### CronJob Class
diff --git a/examples/is_crontime_valid.js b/examples/is_crontime_valid.js
index 8e04f635..443733da 100644
--- a/examples/is_crontime_valid.js
+++ b/examples/is_crontime_valid.js
@@ -1,3 +1,3 @@
-import { isCronTimeValid } from '../src';
+import { validateCronExpression } from '../src';
 
-console.log('is valid? ', isCronTimeValid('NOT VALID'));
+console.log('is valid? ', validateCronExpression('NOT VALID').valid);
diff --git a/src/index.ts b/src/index.ts
index f56b714c..b0a1fdfc 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -21,13 +21,4 @@ export const sendAt = (cronTime: string | Date | DateTime): DateTime =>
 export const timeout = (cronTime: string | Date | DateTime): number =>
 	new CronTime(cronTime).getTimeout();
 
-export const isCronTimeValid = (
-	cronTime: string | Date | DateTime
-): boolean => {
-	try {
-		new CronTime(cronTime);
-		return true;
-	} catch (_) {
-		return false;
-	}
-};
+export const validateCronExpression = CronTime.validateCronExpression;
diff --git a/src/time.ts b/src/time.ts
index 488602e6..66892eef 100644
--- a/src/time.ts
+++ b/src/time.ts
@@ -75,6 +75,23 @@ export class CronTime {
 		}
 	}
 
+	static validateCronExpression(cronExpression: string): {
+		valid: boolean;
+		error?: CronError;
+	} {
+		try {
+			new CronTime(cronExpression);
+			return {
+				valid: true
+			};
+		} catch (error: any) {
+			return {
+				valid: false,
+				error
+			};
+		}
+	}
+
 	private _getWeekDay(date: DateTime) {
 		return date.weekday === 7 ? 0 : date.weekday;
 	}
diff --git a/tests/crontime.test.ts b/tests/crontime.test.ts
index da25710e..ea71bb5c 100644
--- a/tests/crontime.test.ts
+++ b/tests/crontime.test.ts
@@ -1,6 +1,6 @@
 import { DateTime } from 'luxon';
 import sinon from 'sinon';
-import { CronTime, isCronTimeValid } from '../src';
+import { CronTime, validateCronExpression } from '../src';
 
 describe('crontime', () => {
 	// eslint-disable-next-line jest/no-standalone-expect
@@ -779,18 +779,18 @@ describe('crontime', () => {
 	});
 });
 
-describe('isCronTimeValid', () => {
+describe('validateCronExpression', () => {
 	it('should return true for valid cron expressions', () => {
-		expect(isCronTimeValid('* * * * *')).toBe(true);
-		expect(isCronTimeValid('0 0 * * *')).toBe(true);
-		expect(isCronTimeValid('0 0 1 1 *')).toBe(true);
-		expect(isCronTimeValid('*/5 * * * *')).toBe(true);
+		expect(validateCronExpression('* * * * *').valid).toBe(true);
+		expect(validateCronExpression('0 0 * * *').valid).toBe(true);
+		expect(validateCronExpression('0 0 1 1 *').valid).toBe(true);
+		expect(validateCronExpression('*/5 * * * *').valid).toBe(true);
 	});
 
 	it('should return false for invalid cron expressions', () => {
-		expect(isCronTimeValid('* * * *')).toBe(false);
-		expect(isCronTimeValid('60 * * * *')).toBe(false);
-		expect(isCronTimeValid('* * * * * * *')).toBe(false);
-		expect(isCronTimeValid('invalid cron')).toBe(false);
+		expect(validateCronExpression('* * * *').valid).toBe(false);
+		expect(validateCronExpression('60 * * * *').valid).toBe(false);
+		expect(validateCronExpression('* * * * * * *').valid).toBe(false);
+		expect(validateCronExpression('invalid cron').valid).toBe(false);
 	});
 });