Persian Helpers

Persian Helpers is a minimal NodeJS package with a set of helpers/tools specifically for the Persian/Farsi language.

If you like the package and want to see more features being added in, giving it a star would help the project a lot. Thanks!

Table of contents

• Persian Helpers

  • Installation

  • Usage

    • Importing Persian Helpers

    • Converting English digits to Persian or vice versa

    • Separating Persian or English digits in a string or number by commas or any separator

    • Generate Persian or English slugs based on a string

    • Convert digits to words in Persian

  • Contribution

  • License

Installation

NPM:

npm install persian-helpers --save

Yarn:

yarn add persian-helpers

Usage

Importing Persian Helpers:

import * as persianHelpers from "persian-helpers";

// Or alternatively

import { convertDigits } from "persian-helpers";

  

console.log(persianHelpers.convertDigits("1000"));

// Or

console.log(convertDigits("1000"));

Converting English digits to Persian or vice versa

| Options | Description | Default value | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------- | | to (optional) | Target language for converting the digits | fa | | separator (optional) | A property to use separators for digits. For example with separator being enabled, instead of ۱۰۰۰۰۰۰, ۱,۰۰۰,۰۰۰ will be returned. | undefined |

Convert a number to Persian digits

convertDigits(1000); // "۱۰۰۰"

Convert a number to English digits

convertDigits("۱۲۳۴", { to: "en" }); // "1234"

Convert a number to Persian digits with digit separator

Note: separator can be set to any string and {separator: true} is a shorthand for {separator: '٬'}. An example is shown below.

convertDigits(1000, { separator: true }); // "۱٬۰۰۰"

convertDigits("مبلغ این محصول 950000 تومان می باشد.", { separator: true }); // "مبلغ این محصول ۹۵۰٬۰۰۰ تومان می باشد."

Convert a number to Persian digits with custom digit separator

convertDigits(1000, { separator: '-' }); // "۱-۰۰۰"

convertDigits also takes inputs other than number/string as shown below.

Convert a nested array to Persian digits

convertDigits([123, { test: '11۱' }, '4foo5bar6', [789]]); // [ '۱۲۳', { test: '۱۱۱' }, '۴foo۵bar۶', ['۷۸۹'], ]

Separating Persian or English digits in a string or number by commas or any separator

| Options | Description | Default value | | ------------------------ | ------------------------------------------ | ------------- | | separator (optional) | The string used for separating the digits. | , |

Separate digits by commas in a string with Persian numbers

separateDigitsBySeparator('۱۰۰۰۰۰۰'); // "۱,۰۰۰,۰۰۰"

Separate digits by an unique separator in a string with Persian numbers

separateDigitsBySeparator('۱۰۰۰۰۰۰', { separator: '-' }); // "۱-۰۰۰-۰۰۰"

Separate digits by commas in a string containing numbers and letters

separateDigitsBySeparator('مبلغ این محصول ۱۰۰۰۰۰۰ تومان می باشد.'); // "مبلغ این محصول ۱,۰۰۰,۰۰۰ تومان می باشد."

Note: separateDigitsBySeparator also works with English digits or a string mixed with English and Persian digits

Generate Persian or English slugs based on a string

| Options | Description | Default value | | ------------------------------- | ---------------------------------------- | ------------- | | includeUpperCase (optional) | Include upper case letters in the slug | false | | separator (optional) | The separator between spaces in the slug | - | | to (optional) | Target language for the slug | en |

Generate an English slug based on Persian string

generateSlug('سلام دنیا 💕'); // "slam-dnya"

Generate a Persian slug based on Persian string

generateSlug('سلام دنیا 💕'); // "سلام-دنیا"

Generate a Persian slug based on Persian string with an unique separator

generateSlug('سلام دنیا 💕', { separator: ' ' }); // "slam dnya"

Generate an English slug an also include uppercases

generateSlug('پکیج Persian Helper', { includeUpperCase: true }); // "pkyj-Persian-Helper"

Convert digits to words in Persian

| Options | Description | Default value | | ------------------------------- | ---------------------------------------- | ------------- | | ordinal (optional) | Convert digits to ordinal digits | false | | throwErrorIfInvalid (optional) | Throw error if digits cannot be converted | false |

Generate words from a number

convertDigitsToWords(1234) // "یک هزار و دویست و سی و چهار"
convertDigitsToWords(1234.121) // "یک هزار و دویست و سی و چهار ممیز یکصد و بیست و یک هزارم"
convertDigitsToWords(99999) // "نود و نه هزار و نهصد و نود و نه"

Generate words from Persian Digits

convertDigitsToWords('۹۹۹۹۹'); // "نود و نه هزار و نهصد و نود و نه"

Generate ordinal numbers from English/Persian digits

convertDigitsToWords(4, { ordinal: true }); // "چهارم"
convertDigitsToWords(41, { ordinal: true }); // "چهل و یکم"
convertDigitsToWords("۱", { ordinal: true }); // "اول"

Generate words from input but throw error if the input is invalid

convertDigitsToWords('۱', { ordinal: true, throwErrorIfInvalid: true }) // "اول"

convertDigitsToWords('۱d7s9dhsihd', { ordinal: true, throwErrorIfInvalid: true }) // Error: Cannot convert "۱d7s9dhsihd" to words.

Find any bugs/issues? Have suggestions?

If you encountered any issues or bugs while using Persian Helpers, or you want to see a feature getting added, please make sure to open a new issue.

Contribution

Contributions to Persian Helpers are greatly appreciated. To contribute:

1. Fork the Project

2. Create your Feature Branch (git checkout -b feature/NewHelper)

3. Commit your Changes (git commit -m 'Add a NewHelper')

4. Push to the Branch (git push origin feature/NewHelper)

5. Open a Pull Request

License

Persian Helpers is licensed under the MIT License. Visit LICENSE.md for more information.