feat: add date and time conversion support with new tests

- Implemented `convertDateToWords` method for converting both Jalali and Gregorian dates into Persian words.
- Added `convertTimeToWords` method to convert digital time strings ("HH:mm") to Persian words.
- Introduced `customTimePrefix` option for customizing the time prefix (default "ساعت").
- Updated tests to cover new date and time conversion functionalities.
- Updated documentation and usage examples in the README.

Author: rojcode

README.md

@@ -1,25 +1,24 @@
 
-
-# Harfizer - Number to Persian Words  
-**تبدیل عدد به حروف فارسی با TypeScript**
+# Harfizer - Number, Date & Time to Persian Words  
+**تبدیل عدد، تاریخ و زمان به حروف فارسی با TypeScript**
 
 📘 English & فارسی Documentation
 
 ---
 
 ## 📦 Overview | نمای کلی
 
-**Harfizer** is a modern, TypeScript-native package for converting numbers into their **Persian word** representation. It supports integers, decimals, and negative numbers, with rich customization options including separators, lexicons, and decimal suffixes.
-
-**Harfizer** یک پکیج تایپ‌اسکریپتی مدرن برای تبدیل اعداد به **حروف فارسی** است. این پکیج از اعداد صحیح، اعشاری و منفی پشتیبانی می‌کند و با ارائه گزینه‌های متنوع، امکان سفارشی‌سازی کامل خروجی را فراهم می‌سازد.
-
----
+**Harfizer** is a modern, TypeScript-native package for converting numbers into their **Persian word** representation.  
+It supports integers, decimals, and negative numbers with rich customization options (such as separators, lexicons, and decimal suffixes).
 
-## 🙏 Acknowledgements | قدردانی
+In addition to number conversion, Harfizer now supports converting dates and digital time strings into Persian words.  
+This means you can now convert both dates (Solar/Jalali or Gregorian) and digital time (HH:mm) to their Persian word equivalents.
 
-We extend our sincere thanks to the creators of the [num2persian](https://www.npmjs.com/package/num2persian) package — an excellent JavaScript utility that made number-to-Persian-word conversion accessible years ago. Inspired by their work, we created **Harfizer** to provide a fully typed, flexible, and extensible solution for modern TypeScript-based applications.
+**Harfizer** یک پکیج تایپ‌اسکریپتی مدرن برای تبدیل اعداد به **حروف فارسی** است.  
+این پکیج از اعداد صحیح، اعشاری و منفی پشتیبانی می‌کند و با ارائه گزینه‌های متنوع، امکان سفارشی‌سازی کامل خروجی (مانند جداکننده‌ها، واژگان و پسوندهای اعشاری) را فراهم می‌سازد.
 
-ما صمیمانه از تیم پکیج [num2persian](https://www.npmjs.com/package/num2persian) تشکر می‌کنیم؛ ابزاری ارزشمند که سال‌ها پیش امکان تبدیل اعداد به حروف فارسی را در جاوااسکریپت فراهم کرد. به عنوان یک برنامه‌نویس که درگیر توسعه‌ی نرم‌افزارهای فارسی‌زبان هستم، وظیفه خود دانستم تا نسخه‌ای مدرن، امن و قابل گسترش برای TypeScript توسعه دهم و آن را با جامعه به اشتراک بگذارم.
+همچنین، Harfizer از تبدیل تاریخ‌ها و زمان دیجیتال به حروف فارسی پشتیبانی می‌کند.  
+این بدان معناست که اکنون می‌توانید تاریخ (شمسی/میلادی) و زمان (به فرمت HH:mm) را به معادل حروف فارسی آن‌ها تبدیل کنید.
 
 ---
 
@@ -33,6 +32,8 @@ npm install harfizer
 
 ## 🚀 Basic Usage | استفاده ساده
 
+### Converting Numbers | تبدیل عدد
+
 ```ts
 import { HarfizerConverter } from 'harfizer';
 
@@ -45,6 +46,36 @@ console.log(HarfizerConverter.toWords("10500.25"));
 // Output: "ده هزار و پانصد ممیز بیست و پنج صدم"
 ```
 
+### Converting Dates | تبدیل تاریخ
+
+```ts
+import { HarfizerConverter } from 'harfizer';
+
+const converter = new HarfizerConverter();
+
+// Convert a Jalali (Solar) date:
+console.log(converter.convertDateToWords("1404-03-24"));
+// Expected Output: "بیست و چهار خرداد یک هزار و چهارصد و چهار"
+
+// Convert a Gregorian date:
+console.log(converter.convertDateToWords("2023-04-05", "gregorian"));
+// Expected Output: "پنج آوریل دو هزار و بیست و سه"
+```
+
+### Converting Time | تبدیل زمان
+
+```ts
+import { HarfizerConverter } from 'harfizer';
+
+const converter = new HarfizerConverter();
+
+console.log(converter.convertTimeToWords("09:05"));
+// Expected Output: "ساعت نه و پنج دقیقه"
+
+console.log(converter.convertTimeToWords("18:00"));
+// Expected Output: "ساعت هجده"
+```
+
 ---
 
 ## ➖ Negative Numbers | اعداد منفی
@@ -63,16 +94,17 @@ console.log(HarfizerConverter.toWords("-0.01"));
 
 ## ⚙️ Custom Options | تنظیمات سفارشی
 
-شما می‌توانید خروجی Harfizer را با گزینه‌های دلخواه تغییر دهید:
+You can customize the output of Harfizer using the following options:
 
-| Option | Type | Default | توضیح فارسی |
-|--------|------|---------|-------------|
-| `useNegativeWord` | `boolean` | `true` | استفاده از کلمه "منفی" |
-| `customSeparator` | `string` | `" و "` | جداکننده بین بخش‌ها |
-| `customLexicon` | `Lexicon` | پیش‌فرض فارسی | واژگان سفارشی |
-| `customDecimalSuffixes` | `string[]` | پیش‌فرض فارسی | پسوندهای اعشاری |
-| `customNegativeWord` | `string` | `"منفی "` | واژه منفی دلخواه |
-| `customZeroWord` | `string` | `"صفر"` | معادل صفر دلخواه |
+| Option                 | Type         | Default      | توضیح فارسی                           |
+|------------------------|--------------|--------------|----------------------------------------|
+| `useNegativeWord`      | `boolean`    | `true`       | استفاده از کلمه "منفی"                 |
+| `customSeparator`      | `string`     | `" و "`     | جداکننده بین بخش‌ها                   |
+| `customLexicon`        | `Lexicon`    | پیش‌فرض فارسی | واژگان سفارشی                        |
+| `customDecimalSuffixes`| `string[]`   | پیش‌فرض فارسی | پسوندهای اعشاری                     |
+| `customNegativeWord`   | `string`     | `"منفی "`   | واژه منفی دلخواه                      |
+| `customZeroWord`       | `string`     | `"صفر"`     | معادل صفر دلخواه                      |
+| `customTimePrefix`     | `string`     | `"ساعت"`   | پیشوند زمان برای تبدیل زمان          |
 
 ### Examples | مثال‌ها
 
@@ -116,12 +148,24 @@ HarfizerConverter.toWords("0.04", {
 #### ✅ `customLexicon`
 
 ```ts
-const funnyLexicon = [...]; // your own words
+const funnyLexicon = [...]; // واژگان سفارشی خودتان
 
 HarfizerConverter.toWords(12, { customLexicon: funnyLexicon });
 // خروجی: بر اساس واژگان سفارشی
 ```
 
+#### ✅ `customTimePrefix` (برای تبدیل زمان)
+
+```ts
+import { HarfizerConverter, ConversionOptions } from 'harfizer';
+
+const options: ConversionOptions = { customTimePrefix: "زمان" };
+const customConverter = new HarfizerConverter(options);
+
+console.log(customConverter.convertTimeToWords("09:05"));
+// خروجی مورد انتظار: "زمان نه و پنج دقیقه"
+```
+
 ---
 
 ## 🧱 Lexicon Structure | ساختار واژگان
@@ -132,7 +176,7 @@ type Lexicon = [
   tenToTwenty[], // ده تا بیست
   tens[],        // بیست تا نود
   hundreds[],    // یکصد تا نهصد
-  scales[],      // هزار، میلیون، میلیارد و ...
+  scales[]       // هزار، میلیون، میلیارد و ...
 ];
 ```
 
@@ -145,32 +189,32 @@ type Lexicon = [
 ```ts
 const converter = new HarfizerConverter({ customZeroWord: "هیچ" });
 
-converter.convert("0.75");
+console.log(converter.convert("0.75"));
 // خروجی: "هفتاد و پنج صدم"
 ```
 
-### Convert triple digits only:
+### Convert Triple Digits Only | تبدیل تنها ارقام سه رقمی
 
 ```ts
-converter.convertTripleToWords(215);
+console.log(converter.convertTripleToWords(215));
 // خروجی: "دویست و پانزده"
 ```
 
 ---
-## 📆 Date Conversion | تبدیل تاریخ
-
-Harfizer now supports converting dates to their Persian word representation using the `convertDateToWords` method. This method accepts a date string in either `YYYY/MM/DD` or `YYYY-MM-DD` format, along with an optional calendar type (`"jalali"` for Solar dates or `"gregorian"` for Gregorian dates, default is `"jalali"`).
 
-Harfizer اکنون از تبدیل تاریخ به حروف فارسی پشتیبانی می‌کند. با استفاده از متد `convertDateToWords` می‌توانید تاریخ‌ها را به رشته‌ای از حروف تبدیل کنید. این متد یک رشته تاریخ به فرمت `YYYY/MM/DD` یا `YYYY-MM-DD` و یک پارامتر تقویم اختیاری (`"jalali"` برای تاریخ شمسی یا `"gregorian"` برای تاریخ میلادی، پیش‌فرض `"jalali"`) را دریافت می‌کند.
+## 📆 Date Conversion | تبدیل تاریخ
 
-### Example | مثال
+Harfizer supports converting dates to their Persian word representation using the `convertDateToWords` method.  
+This method accepts a date string in either `YYYY/MM/DD` or `YYYY-MM-DD` format and an optional calendar type:
+- `"jalali"` for Solar dates (default)
+- `"gregorian"` for Gregorian dates
 
 ```ts
 import { HarfizerConverter } from 'harfizer';
 
 const converter = new HarfizerConverter();
 
-// Convert a Jalali (Solar) date using dash format:
+// Convert a Jalali (Solar) date:
 console.log(converter.convertDateToWords("1404-03-24"));
 // Expected Output: "بیست و چهار خرداد یک هزار و چهارصد و چهار"
 
@@ -179,17 +223,39 @@ console.log(converter.convertDateToWords("2023-04-05", "gregorian"));
 // Expected Output: "پنج آوریل دو هزار و بیست و سه"
 ```
 
+---
+
+## ⏰ Time Conversion | تبدیل زمان
+
+Harfizer also converts digital time strings to Persian words using the `convertTimeToWords` method.  
+It accepts a time string in the format `"HH:mm"` and returns its Persian word representation.  
+A custom time prefix can be provided via `customTimePrefix` (default is `"ساعت"`).
+
+```ts
+import { HarfizerConverter } from 'harfizer';
+
+const converter = new HarfizerConverter();
+
+console.log(converter.convertTimeToWords("09:05"));
+// Expected Output: "ساعت نه و پنج دقیقه"
+
+console.log(converter.convertTimeToWords("18:00"));
+// Expected Output: "ساعت هجده"
+```
+
+---
 
 ## 📏 Limitations | محدودیت‌ها
 
-- حداکثر عدد ورودی: 66 رقم (برای اعداد صحیح)
-- پشتیبانی از حداکثر 11 رقم اعشار
-- ورودی فقط باید عددی باشد (مقدارهای غیرعددی پشتیبانی نمی‌شوند)
+- **عدد:** حداکثر عدد ورودی 66 رقم (برای اعداد صحیح)
+- **اعشار:** پشتیبانی از حداکثر 11 رقم اعشار
+- **تاریخ:** فرمت‌های پشتیبانی شده `YYYY/MM/DD` و `YYYY-MM-DD`
+- **زمان:** فرمت پشتیبانی شده برای زمان تنها `"HH:mm"` است.
+- ورودی فقط باید عددی (برای تبدیل عدد) یا رشته‌های معتبر برای تاریخ و زمان باشد.
 
 ---
 
 ## 📚 License | مجوز
 
 **MIT License**  
 کاملاً متن‌باز و رایگان برای استفاده تجاری و شخصی.
-

package.json

@@ -8,13 +8,23 @@
     "build": "tsc",
     "test": "jest"
   },
-  "keywords": [
+   "keywords": [
     "persian-numbers",
     "number-to-words",
     "persian-words",
     "harfizer",
     "num2persian",
-    "typescript"
+    "typescript",
+    "date-to-words",
+    "time-to-words",
+    "persian-date",
+    "persian-time",
+    "jalali-date",
+    "gregorian-date",
+    "date-conversion",
+    "time-conversion",
+    "persian-datetime",
+    "datetime-to-words"
   ],
   "repository": {
     "type": "git",

src/harfizer.test.ts

@@ -136,4 +136,39 @@ describe("HarfizerConverter", () => {
       expect(result).toBe("پنج آوریل دو هزار و بیست و سه");
     });
   });
+
+  describe("convertTimeToWords", () => {
+    let converter: HarfizerConverter;
+
+    beforeEach(() => {
+      converter = new HarfizerConverter();
+    });
+
+    test("should convert time '09:05' with default prefix", () => {
+      const result = converter.convertTimeToWords("09:05");
+      // Expected conversion: "ساعت نه و پنج دقیقه"
+      expect(result).toBe("ساعت نه و پنج دقیقه");
+    });
+
+    test("should convert time '18:00' with default prefix", () => {
+      const result = converter.convertTimeToWords("18:00");
+      // Expected conversion: "ساعت هجده"
+      expect(result).toBe("ساعت هجده");
+    });
+
+    test("should convert time with custom time prefix", () => {
+      const customConverter = new HarfizerConverter({
+        customTimePrefix: "زمان",
+      });
+      const result = customConverter.convertTimeToWords("09:05");
+      // Expected conversion with custom prefix: "زمان نه و پنج دقیقه"
+      expect(result).toBe("زمان نه و پنج دقیقه");
+    });
+
+    test("should throw error for invalid time format", () => {
+      expect(() => converter.convertTimeToWords("9-05")).toThrow(
+        "Invalid time format. Expected format 'HH:mm'."
+      );
+    });
+  });
 });

src/harfizer.ts

@@ -17,6 +17,7 @@ export type Lexicon = string[][];
  * @property {string[]} [customDecimalSuffixes] - Custom array of suffixes for the fractional part.
  * @property {string} [customNegativeWord] - Custom word to denote negative numbers.
  * @property {string} [customZeroWord] - Custom word to represent zero.
+ * @property {string} [customTimePrefix] - Custom prefix for time conversion (e.g. "ساعت" or any other text).
  */
 export interface ConversionOptions {
   useNegativeWord?: boolean;
@@ -25,6 +26,7 @@ export interface ConversionOptions {
   customDecimalSuffixes?: string[];
   customNegativeWord?: string;
   customZeroWord?: string;
+  customTimePrefix?: string;
 }
 
 /**
@@ -428,6 +430,57 @@ export class HarfizerConverter implements IConverter {
     return `${dayWords} ${monthName} ${yearWords}`;
   }
 
+  /**
+   * Converts a digital time string (HH:mm) to its Persian word representation.
+   *
+   * @param {string} timeStr - The time string in "HH:mm" format.
+   * @returns {string} The word representation of the time.
+   * @throws {Error} Throws an error if the time format is invalid or if time values are out of range.
+   */
+  public convertTimeToWords(timeStr: string): string {
+    // Split the time string using colon (":") as the separator.
+    const parts = timeStr.split(":");
+    if (parts.length !== 2) {
+      throw new Error("Invalid time format. Expected format 'HH:mm'.");
+    }
+    const [hourStr, minuteStr] = parts;
+
+    // Parse hours and minutes.
+    const hour = parseInt(hourStr, 10);
+    const minute = parseInt(minuteStr, 10);
+
+    if (isNaN(hour) || isNaN(minute)) {
+      throw new Error(
+        "Invalid time format. Hours and minutes should be numbers."
+      );
+    }
+
+    // Validate hour and minute ranges.
+    if (hour < 0 || hour > 23) {
+      throw new Error("Invalid hour value. Hour should be between 0 and 23.");
+    }
+    if (minute < 0 || minute > 59) {
+      throw new Error(
+        "Invalid minute value. Minute should be between 0 and 59."
+      );
+    }
+
+    // Retrieve the custom time prefix from configuration or use the default "ساعت".
+    const timePrefix = this.config.customTimePrefix ?? "ساعت";
+
+    // Convert the hour and minute values to their word representations.
+    const hourWords = this.convert(hour);
+    const minuteWords = this.convert(minute);
+
+    // Construct the final time string in words.
+    // If minutes are zero, return only the hour part.
+    if (minute === 0) {
+      return `${timePrefix} ${hourWords}`;
+    } else {
+      return `${timePrefix} ${hourWords} و ${minuteWords} دقیقه`;
+    }
+  }
+
   /**
    * Returns the default separator from the configuration or default constant.
    *