Skip to content

Commit 009c349

Browse files
rojcoderojcode
committed
1.0.3 update
1 parent 7f947ff commit 009c349

50 files changed

Lines changed: 6112 additions & 795 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎README.md‎

Lines changed: 112 additions & 193 deletions
Original file line numberDiff line numberDiff line change
@@ -1,261 +1,180 @@
11

2-
# Harfizer - Number, Date & Time to Persian Words
3-
**تبدیل عدد، تاریخ و زمان به حروف فارسی با TypeScript**
42

5-
📘 English & فارسی Documentation
3+
# Harfizer — Say Your Numbers, Dates, and Times Out Loud (in Any Language!)
64

7-
---
8-
9-
## 📦 Overview | نمای کلی
5+
**Harfizer** is a powerful package for converting numbers, dates, and times into words. It supports multiple languages including [🇮🇷 Persian](./docs/persian.md), [🇫🇷 French](./docs/french.md), [🇯🇵 Japanese](./docs/japanese.md), [🇨🇳 Chinese](./docs/chinese.md), [🇷🇺 Russian](./docs/russian.md), [🇩🇪 German](./docs/german.md), and [🇪🇸 Spanish](./docs/spanish.md). By using language-specific plugins, Harfizer allows you to easily convert numeric and temporal values into their textual representations.
6+
If you prefer a language other than English, please check the respective documentation by clicking on the links provided above or at the end of this document.
107

11-
**Harfizer** is a modern, TypeScript-native package for converting numbers into their **Persian word** representation.
12-
It supports integers, decimals, and negative numbers with rich customization options (such as separators, lexicons, and decimal suffixes).
138

14-
In addition to number conversion, Harfizer now supports converting dates and digital time strings into Persian words.
15-
This means you can now convert both dates (Solar/Jalali or Gregorian) and digital time (HH:mm) to their Persian word equivalents.
9+
## Table of Contents
10+
- [Harfizer — Say Your Numbers, Dates, and Times Out Loud (in Any Language!)](#harfizer--say-your-numbers-dates-and-times-out-loud-in-any-language)
11+
- [Table of Contents](#table-of-contents)
12+
- [Installation](#installation)
13+
- [Usage](#usage)
14+
- [Methods](#methods)
15+
- [`convertNumber(input: InputNumber, options?: ConversionOptions): string`](#convertnumberinput-inputnumber-options-conversionoptions-string)
16+
- [`convertTripleToWords(num: InputNumber, lexicon?: any, _separator?: string): string`](#converttripletowordsnum-inputnumber-lexicon-any-_separator-string-string)
17+
- [`convertDateToWords(dateStr: string, calendar?: "jalali" | "gregorian"): string`](#convertdatetowordsdatestr-string-calendar-jalali--gregorian-string)
18+
- [`convertTimeToWords(timeStr: string): string`](#converttimetowordstimestr-string-string)
19+
- [Examples](#examples)
20+
- [Additional Options](#additional-options)
21+
- [Other Language Plugins Documentation](#other-language-plugins-documentation)
22+
- [License](#license)
1623

17-
**Harfizer** یک پکیج تایپ‌اسکریپتی مدرن برای تبدیل اعداد به **حروف فارسی** است.
18-
این پکیج از اعداد صحیح، اعشاری و منفی پشتیبانی می‌کند و با ارائه گزینه‌های متنوع، امکان سفارشی‌سازی کامل خروجی (مانند جداکننده‌ها، واژگان و پسوندهای اعشاری) را فراهم می‌سازد.
24+
## Installation
1925

20-
همچنین، Harfizer از تبدیل تاریخ‌ها و زمان دیجیتال به حروف فارسی پشتیبانی می‌کند.
21-
این بدان معناست که اکنون می‌توانید تاریخ (شمسی/میلادی) و زمان (به فرمت HH:mm) را به معادل حروف فارسی آن‌ها تبدیل کنید.
22-
23-
---
24-
25-
## 🛠 Installation | نصب
26+
Install Harfizer via npm:
2627

2728
```bash
2829
npm install harfizer
2930
```
3031

31-
---
32-
33-
## 🚀 Basic Usage | استفاده ساده
32+
## Usage
3433

35-
### Converting Numbers | تبدیل عدد
34+
Import the plugin and the `CoreConverter` from the package:
3635

37-
```ts
38-
import { HarfizerConverter } from 'harfizer';
36+
```typescript
37+
import { CoreConverter, EnglishLanguagePlugin } from 'harfizer';
3938

40-
console.log(HarfizerConverter.toWords(1234));
41-
// Output: "یک هزار و دویست و سی و چهار"
39+
const englishPlugin = new EnglishLanguagePlugin();
40+
const converter = new CoreConverter(englishPlugin);
4241
```
4342

44-
```ts
45-
console.log(HarfizerConverter.toWords("10500.25"));
46-
// Output: "ده هزار و پانصد ممیز بیست و پنج صدم"
47-
```
48-
49-
### Converting Dates | تبدیل تاریخ
50-
51-
```ts
52-
import { HarfizerConverter } from 'harfizer';
43+
## Methods
5344

54-
const converter = new HarfizerConverter();
55-
56-
// Convert a Jalali (Solar) date:
57-
console.log(converter.convertDateToWords("1404-03-24"));
58-
// Expected Output: "بیست و چهار خرداد یک هزار و چهارصد و چهار"
59-
60-
// Convert a Gregorian date:
61-
console.log(converter.convertDateToWords("2023-04-05", "gregorian"));
62-
// Expected Output: "پنج آوریل دو هزار و بیست و سه"
63-
```
45+
### `convertNumber(input: InputNumber, options?: ConversionOptions): string`
46+
Converts a given number (integer or decimal, possibly negative) into its English textual form. It handles the fractional part digit-by-digit using the word "point".
6447

65-
### Converting Time | تبدیل زمان
48+
**Parameters:**
49+
- **input:** A number, numeric string, or bigint.
50+
- **options (optional):** An object to customize conversion:
51+
- `customZeroWord` – overrides the default word for zero.
52+
- `customNegativeWord` – overrides the default negative word.
53+
- `customSeparator` – overrides the default token separator.
6654

67-
```ts
68-
import { HarfizerConverter } from 'harfizer';
55+
**Returns:**
56+
A string representing the number in words.
6957

70-
const converter = new HarfizerConverter();
58+
**Example:**
7159

72-
console.log(converter.convertTimeToWords("09:05"));
73-
// Expected Output: "ساعت نه و پنج دقیقه"
60+
```typescript
61+
converter.convertNumber("123");
62+
// Output: "one hundred twenty-three"
7463

75-
console.log(converter.convertTimeToWords("18:00"));
76-
// Expected Output: "ساعت هجده"
64+
converter.convertNumber("-456.78");
65+
// Output: "minus four hundred fifty-six point seven eight"
7766
```
7867

7968
---
8069

81-
## ➖ Negative Numbers | اعداد منفی
70+
### `convertTripleToWords(num: InputNumber, lexicon?: any, _separator?: string): string`
71+
Converts a three-digit (or fewer) number into its English textual representation.
8272

83-
```ts
84-
console.log(HarfizerConverter.toWords(-72));
85-
// Output: "منفی هفتاد و دو"
86-
```
87-
88-
```ts
89-
console.log(HarfizerConverter.toWords("-0.01"));
90-
// Output: "منفی یک صدم"
91-
```
92-
93-
---
94-
95-
## ⚙️ Custom Options | تنظیمات سفارشی
73+
**Parameters:**
74+
- **num:** A numeric value (up to 3 digits).
9675

97-
You can customize the output of Harfizer using the following options:
76+
**Returns:**
77+
A string representing the three-digit number (e.g., "four hundred fifty-six").
9878

99-
| Option | Type | Default | توضیح فارسی |
100-
|------------------------|--------------|--------------|----------------------------------------|
101-
| `useNegativeWord` | `boolean` | `true` | استفاده از کلمه "منفی" |
102-
| `customSeparator` | `string` | `" و "` | جداکننده بین بخش‌ها |
103-
| `customLexicon` | `Lexicon` | پیش‌فرض فارسی | واژگان سفارشی |
104-
| `customDecimalSuffixes`| `string[]` | پیش‌فرض فارسی | پسوندهای اعشاری |
105-
| `customNegativeWord` | `string` | `"منفی "` | واژه منفی دلخواه |
106-
| `customZeroWord` | `string` | `"صفر"` | معادل صفر دلخواه |
107-
| `customTimePrefix` | `string` | `"ساعت"` | پیشوند زمان برای تبدیل زمان |
79+
**Example:**
10880

109-
### Examples | مثال‌ها
110-
111-
#### ✅ `useNegativeWord`
112-
113-
```ts
114-
HarfizerConverter.toWords(-45, { useNegativeWord: false });
115-
// خروجی: "چهل و پنج"
116-
```
117-
118-
#### ✅ `customSeparator`
119-
120-
```ts
121-
HarfizerConverter.toWords(123456, { customSeparator: "، " });
122-
// خروجی: "یکصد و بیست و سه هزار، چهارصد و پنجاه و شش"
81+
```typescript
82+
converter.convertTripleToWords(789);
83+
// Output: "seven hundred eighty-nine"
12384
```
12485

125-
#### ✅ `customNegativeWord`
126-
127-
```ts
128-
HarfizerConverter.toWords(-12, { customNegativeWord: "عدد منفی " });
129-
// خروجی: "عدد منفی دوازده"
130-
```
131-
132-
#### ✅ `customZeroWord`
133-
134-
```ts
135-
HarfizerConverter.toWords(0, { customZeroWord: "هیچ" });
136-
// خروجی: "هیچ"
137-
```
138-
139-
#### ✅ `customDecimalSuffixes`
140-
141-
```ts
142-
HarfizerConverter.toWords("0.04", {
143-
customDecimalSuffixes: ["", "دهم", "صدم", "هزارم", "ده‌هزارم"]
144-
});
145-
// خروجی: "چهار صدم"
146-
```
147-
148-
#### ✅ `customLexicon`
149-
150-
```ts
151-
const funnyLexicon = [...]; // واژگان سفارشی خودتان
152-
153-
HarfizerConverter.toWords(12, { customLexicon: funnyLexicon });
154-
// خروجی: بر اساس واژگان سفارشی
155-
```
156-
157-
#### ✅ `customTimePrefix` (برای تبدیل زمان)
158-
159-
```ts
160-
import { HarfizerConverter, ConversionOptions } from 'harfizer';
86+
---
16187

162-
const options: ConversionOptions = { customTimePrefix: "زمان" };
163-
const customConverter = new HarfizerConverter(options);
88+
### `convertDateToWords(dateStr: string, calendar?: "jalali" | "gregorian"): string`
89+
Converts a Gregorian date string (formatted as "YYYY/MM/DD" or "YYYY-MM-DD") into its English textual representation in the format "Month Day, Year".
16490

165-
console.log(customConverter.convertTimeToWords("09:05"));
166-
// خروجی مورد انتظار: "زمان نه و پنج دقیقه"
167-
```
91+
**Parameters:**
92+
- **dateStr:** The date string.
93+
- **calendar (optional):** For English, use "gregorian" (default is "gregorian").
16894

169-
---
95+
**Returns:**
96+
A string representing the date in words.
17097

171-
## 🧱 Lexicon Structure | ساختار واژگان
98+
**Example:**
17299

173-
```ts
174-
type Lexicon = [
175-
units[], // یک تا نه
176-
tenToTwenty[], // ده تا بیست
177-
tens[], // بیست تا نود
178-
hundreds[], // یکصد تا نهصد
179-
scales[] // هزار، میلیون، میلیارد و ...
180-
];
100+
```typescript
101+
converter.convertDateToWords("2023/04/05");
102+
// Output: "April 5, two thousand twenty-three"
181103
```
182104

183105
---
184106

185-
## 💼 Advanced Usage | استفاده پیشرفته
107+
### `convertTimeToWords(timeStr: string): string`
108+
Converts a time string in "HH:mm" format into its English textual representation.
109+
If minutes are zero, returns "It is <hour> o'clock"; otherwise, returns "It is <hour> o'clock and <minute> minutes".
186110

187-
### Instance-based usage:
111+
**Parameters:**
112+
- **timeStr:** A time string in "HH:mm" format.
188113

189-
```ts
190-
const converter = new HarfizerConverter({ customZeroWord: "هیچ" });
114+
**Returns:**
115+
A string representing the time in words.
191116

192-
console.log(converter.convert("0.75"));
193-
// خروجی: "هفتاد و پنج صدم"
194-
```
117+
**Example:**
195118

196-
### Convert Triple Digits Only | تبدیل تنها ارقام سه رقمی
119+
```typescript
120+
converter.convertTimeToWords("09:00");
121+
// Output: "It is nine o'clock"
197122

198-
```ts
199-
console.log(converter.convertTripleToWords(215));
200-
// خروجی: "دویست و پانزده"
123+
converter.convertTimeToWords("09:05");
124+
// Output: "It is nine o'clock and five minutes"
201125
```
202126

203-
---
127+
## Examples
204128

205-
## 📆 Date Conversion | تبدیل تاریخ
129+
Here is an example of using the `EnglishLanguagePlugin` with `CoreConverter`:
206130

207-
Harfizer supports converting dates to their Persian word representation using the `convertDateToWords` method.
208-
This method accepts a date string in either `YYYY/MM/DD` or `YYYY-MM-DD` format and an optional calendar type:
209-
- `"jalali"` for Solar dates (default)
210-
- `"gregorian"` for Gregorian dates
131+
```typescript
132+
import { CoreConverter, EnglishLanguagePlugin } from 'harfizer';
211133

212-
```ts
213-
import { HarfizerConverter } from 'harfizer';
134+
const englishPlugin = new EnglishLanguagePlugin();
135+
const converter = new CoreConverter(englishPlugin);
214136

215-
const converter = new HarfizerConverter();
137+
console.log(converter.convertNumber("123"));
138+
// Output: "one hundred twenty-three"
216139

217-
// Convert a Jalali (Solar) date:
218-
console.log(converter.convertDateToWords("1404-03-24"));
219-
// Expected Output: "بیست و چهار خرداد یک هزار و چهارصد و چهار"
140+
console.log(converter.convertDateToWords("2023/04/05"));
141+
// Output: "April 5, two thousand twenty-three"
220142

221-
// Convert a Gregorian date:
222-
console.log(converter.convertDateToWords("2023-04-05", "gregorian"));
223-
// Expected Output: "پنج آوریل دو هزار و بیست و سه"
143+
console.log(converter.convertTimeToWords("09:05"));
144+
// Output: "It is nine o'clock and five minutes"
224145
```
225146

226-
---
227-
228-
## ⏰ Time Conversion | تبدیل زمان
147+
## Additional Options
229148

230-
Harfizer also converts digital time strings to Persian words using the `convertTimeToWords` method.
231-
It accepts a time string in the format `"HH:mm"` and returns its Persian word representation.
232-
A custom time prefix can be provided via `customTimePrefix` (default is `"ساعت"`).
149+
The `convertNumber` method accepts an optional `ConversionOptions` object for customizing conversion:
233150

234-
```ts
235-
import { HarfizerConverter } from 'harfizer';
151+
```typescript
152+
const options = {
153+
customZeroWord: "nil",
154+
customNegativeWord: "negative",
155+
customSeparator: " "
156+
};
236157

237-
const converter = new HarfizerConverter();
158+
console.log(converter.convertNumber("-123", options));
159+
// Output: "negative one hundred twenty-three"
160+
```
238161

239-
console.log(converter.convertTimeToWords("09:05"));
240-
// Expected Output: "ساعت نه و پنج دقیقه"
162+
## Other Language Plugins Documentation
241163

242-
console.log(converter.convertTimeToWords("18:00"));
243-
// Expected Output: "ساعت هجده"
244-
```
164+
For documentation on other language plugins, please refer to the following files:
245165

246-
---
166+
- [🇬🇧 EnglishLanguagePlugin Documentation](./README.md)
167+
- [🇮🇷 PersianLanguagePlugin Documentation](./docs/persian.md)
168+
- [🇫🇷 FrenchLanguagePlugin Documentation](./docs/french.md)
169+
- [🇯🇵 JapaneseLanguagePlugin Documentation](./docs/japanese.md)
170+
- [🇨🇳 ChineseLanguagePlugin Documentation](./docs/chinese.md)
171+
- [🇷🇺 RussianLanguagePlugin Documentation](./docs/russian.md)
172+
- [🇩🇪 GermanLanguagePlugin Documentation](./docs/german.md)
173+
- [🇪🇸 SpanishLanguagePlugin Documentation](./docs/spanish.md)
247174

248-
## 📏 Limitations | محدودیت‌ها
249175

250-
- **عدد:** حداکثر عدد ورودی 66 رقم (برای اعداد صحیح)
251-
- **اعشار:** پشتیبانی از حداکثر 11 رقم اعشار
252-
- **تاریخ:** فرمت‌های پشتیبانی شده `YYYY/MM/DD` و `YYYY-MM-DD`
253-
- **زمان:** فرمت پشتیبانی شده برای زمان تنها `"HH:mm"` است.
254-
- ورودی فقط باید عددی (برای تبدیل عدد) یا رشته‌های معتبر برای تاریخ و زمان باشد.
255176

256-
---
177+
## License
257178

258-
## 📚 License | مجوز
179+
This package is licensed under the MIT License.
259180

260-
**MIT License**
261-
کاملاً متن‌باز و رایگان برای استفاده تجاری و شخصی.

0 commit comments

Comments
 (0)