npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@codetrend/persian-tools

v4.0.1

Published

An anthology of a variety of tools for Persian language in javascript

Downloads

46

Readme

Rate on Openbase CI/CD codecov GitHub license PRs Welcome CodeFactor GitHub contributors Wallaby.js

Features

Getting started

There are two main ways to get PersianTools.js in your JavaScript project: via script tags or by installing it from NPM and using a build tool like Parcel, WebPack, or Rollup.

via Script Tag

Add the following code to an HTML file:

<html>
<head>
    <!-- Load PersianTools.js -->
    <script src="https://cdn.jsdelivr.net/npm/@persian-tools/persian-tools/build/persian-tools.umd.js"></script>

    <!-- Place your code in the script tag below. You can also use an external .js file -->
    <script type="text/javascript">
        // Notice there is no 'import' statement. 'all persian-tools functions like digitsEnToFa, etc...' is available on the index-page
        // because of the script tag above.

        // Takes a string made of English digits only, and returns a string that represents the same number but with Persian digits
        var convertToFa = PersianTools.digitsEnToFa(1234567);

        // etc...
    </script>
</head>

<body></body>
</html>

Open up that html file in your browser, and the code should run!

Install

Install the PersianTools to your project using yarn or npm. Note: Because we use ES2017 syntax (such as import), this workflow assumes you are using a modern browser, or a bundler/transpiler to convert your code to something older browsers understand.

$ npm install --save @persian-tools/persian-tools

or

$ yarn add @persian-tools/persian-tools

Simple usage

import * as persianTools from "@persian-tools/persian-tools";
// or
import { digitsEnToFa } from "@persian-tools/persian-tools";

// Takes a string made of English digits only, and returns a string that represents the same number but with Persian digits
const convertedToFa = persianTools.digitsEnToFa(1234567);
// or
const convertedToFa = digitsEnToFa(1234567);

Usage

Let's take a look at what an example test case would look like using Persian-tools.

Convert Persian words to the number

| Options | Description | Default |--- |--- |--- | fuzzy(Beta) | Fix typo in the Persian words by using levenshtein algorithm | false | digits | Result will be converted to the English or Persian digits | en | addCommas | Commas will be added to the Result | false

  • Convert with no option
import { wordsToNumber } from "@persian-tools/persian-tools";

wordsToNumber("منفی سه هزارمین") // -3000
wordsToNumber("منفی سه هزارم") // -3000
wordsToNumber("منفی سه هزار") // -3000
wordsToNumber("سه هزار دویست و دوازده") // 3212
wordsToNumber("دوازده هزار بیست دو") // 12022
  • Digits converter
wordsToNumber("منفی سه هزارمین", { digits: "fa" }) // "-۳۰۰۰"
wordsToNumber("دوازده هزار بیست دو", { digits: "fa" }) // ۱۲۰۲۲
  • Add commas
wordsToNumber("منفی سه هزارمین", { addCommas: true }) // "-3,000"
wordsToNumber("دوازده هزار بیست دو", { addCommas: true }) // "12,022"
  • Fuzzy typo fixer(v1.5.0):
import { WordsToNumber } from "@persian-tools/persian-tools";

wordsToNumber("یگصد و بنجاه هزار", { fuzzy: true }) // "150000"  
wordsToNumber("دویشت ر بیشت هزار", { fuzzy: true }) // "220000"  
wordsToNumber("منقی ضد", { fuzzy: true }) // "-100"  

Convert Numbers to Persian words

import { numberToWords } from "@persian-tools/persian-tools";

numberToWords(500443) // "پانصد هزار و چهار صد و چهل و سه"
numberToWords("500,443") // "پانصد هزار و چهار صد و چهل و سه"
numberToWords("500,443", { ordinal: true }) // "پانصد هزار و چهار صد و چهل و سوم"
numberToWords(30000000000) // "سی میلیارد"

NOTE: This function supports the largest safe integer (9007199254740991 / 2^53 - 1)

Add and remove commas

import { addCommas, removeCommas } from "@persian-tools/persian-tools";

addCommas(30000000) // "30,000,000"

removeCommas("30,000,000") // 30000000

Convert Persian numbers to Arabic or English numbers and vice versa

import { digitsArToFa, digitsArToEn, digitsEnToFa, digitsFaToEn , digitsEnToAr, digitsFaToAr } from "@persian-tools/persian-tools";

digitsArToFa("۸۹123۴۵"); // "۸۹123۴۵"

digitsArToEn("٨٩123٤٥"); // "8912345"

digitsEnToFa("123۴۵۶"); // "۱۲۳۴۵۶"

digitsEnToAr("123٤٥٦"); // "۱۲۳٤٥٦"

digitsFaToAr("۱۷۸۲۳۴۰۵۶۹") // ١٧٨٢٣٤٠٥٦٩

Validate Iranian national number(code-e Melli)

import { verifyIranianNationalId, getPlaceByIranNationalId } from "@persian-tools/persian-tools";

verifyIranianNationalId("0499370899"); // true
verifyIranianNationalId("0684159415"); // false

Validate Iranian legal id(shenase hoghoghi)

import { verifyIranianLegalId } from "@persian-tools/persian-tools";

verifyIranianLegalId(10380285692) // false
verifyIranianLegalId(10380284790) // true

Find city and province name by national-id(code-e Melli)

getPlaceByIranNationalId("0084575948").city; // "تهران مرکزی"

Bank number validation and get the name of the bank by bank account number

import { verifyCardNumber, getBankNameFromCardNumber } from "@persian-tools/persian-tools";

verifyCardNumber(6037701689095443); // true

getBankNameFromCardNumber("6219861034529007"); // "بانک سامان"

Validate the correctness of the text of the Persian language and clear the Arabic letters in the Persian text.

import { isPersian, hasPersian, toPersianChars } from "@persian-tools/persian-tools";

isPersian("این یک متن فارسی است؟") // true
isPersian("Lorem Ipsum Test") // false
isPersian("هل هذا نص فارسي؟")// false

hasPersian("This text includes فارسی") // true

toPersianChars("علي") // علی

Note: You can pass 2 more options to isPersian to customize it as your needs:

  • isComplex: If you pass true, Then it accepts some of regular arabic characters which are commons in persian texts.(default is false)
  • trimPattern: By default the function skips some of characters e.g. "'-+()؟. and whitespaces. You can pass your own customized regex as you need.

Fix Persian characters in URL.

import { URLfix } from "@persian-tools/persian-tools";

URLfix(
	"https://fa.wikipedia.org/wiki/%D9%85%D8%AF%DB%8C%D8%A7%D9%88%DB%8C%DA%A9%DB%8C:Gadget-Extra-Editbuttons-botworks.js",
); // "https://fa.wikipedia.org/wiki/مدیاویکی:Gadget-Extra-Editbuttons-botworks.js"
URLfix("https://en.wikipedia.org/wiki/Persian_alphabet"); // "https://en.wikipedia.org/wiki/Persian_alphabet",
URLfix("Sample Text"); // "Sample Text"

Bill calculator

| Method | Description | Return type |--- |--- |--- | getResult | Result of bill calculated information | BillResult | getAmount | Calculate Bill amount by payment id and bill id which entered by the Bill constructor | number | getBillType | Get Bill provider type name | BillTypes | getBarcode | Calculate and get Bill's barcode | string | verificationBill | Validate entered both Bill id and payment id, and return true if bill id and payment id relation was true | boolean | verificationBillId | Validate entered Bill id | boolean | verificationBillPayment | Validate entered Bill payment id | boolean

import { Bill } from "@persian-tools/persian-tools";

// Calculate bill amount by bill id and payment id
// Convert to Iranian Rials
// Return bill amount by Toman(Iranian currency type) by default
new Bill({ billId: 1117753200140, paymentId: 12070160, currency: "rial" }).getResult().amount; // 120000

// Find Bill's type by bill id and payment id
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().type; // تلفن ثابت
new Bill({ billId: 9174639504124, paymentId: 12908197 }).getResult().type; // برق
new Bill({ billId: 2050327604613, paymentId: 1070189 }).getResult().type; // آب
new Bill({ billId: 9100074409151, paymentId: 12908190 }).getResult().type; // تلفن همراه
new Bill({ billId: 7748317800105, paymentId: 1770160 }).getResult().type; // unknown

// Check Bill id validation
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().isValidBillId; // true
new Bill({ billId: 2234322344613, paymentId: 1070189 }).getResult().isValidBillId; // false

// Check Bill's payment id validation
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().isValidBillPayment; // true
new Bill({ billId: 9174639504124, paymentId: 12908197 }).getResult().isValidBillPayment; // false

// Check Bill id and payment id relations which is valid or not
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().isValid; // true
new Bill({ billId: 2234322344613, paymentId: 1070189 }).getResult().isValid; // false

// Get barcode from billId and paymentId
new Bill({ billId: 7748317800142, paymentId: 1770160 }).getResult().barcode; // 77483178001420001770160
new Bill({ billId: 9174639504124, paymentId: 12908197 }).getResult().barcode; // 917463950412400012908197

// Get bill bill id and payment id by bill's barcode
new Bill({ barcode: "22343223446130001070189" }).findByBarcode(); // { billId: 2234322344613 , paymentId: 1070189 }

Iranian Sheba(IBAN)

  • Check validation
import { isShebaValid } from "@persian-tools/persian-tools";

isShebaValid("IR820540102680020817909002"); // true
isShebaValid("IR01234567890123456789"); // false
  • Recognize bank information
import { getShebaInfo } from "@persian-tools/persian-tools";

getShebaInfo("IR820540102680020817909002");
/*
 Result: {
    "nickname": "parsian",
    "name": "Parsian Bank",
    "persianName": "بانک پارسیان",
    "code": "054",
    "accountNumberAvailable": true,
    "accountNumber": "020817909002",
    "formattedAccountNumber": "002-00817909-002"
  }
*/

Fix Persian zero-width non-joiner(Replace spaces by half-space)

import { halfSpace } from "@persian-tools/persian-tools";

halfSpace("نمی ‌خواهی درخت ها را ببینیم؟") // "نمی‌خواهی درخت‌ها را ببینیم؟"

Get information(province, category, type) about vehicles plate

| Properties | Description | Return type |--- |--- |--- | info | provide info about plate | PlateResultApi | isValid | checks if plate is valid or not | boolean

Usage

import { Plate } from "@persian-tools/persian-tools";

Plate("12D45147"); // passing string argument

// or passing in object style
Plate({
  number: "1245147",
  char: "الف"
})
  • Getting info about plate
import { Plate } from "@persian-tools/persian-tools";

Plate("12D45147").info;
/*
  {
  	template: 12 D 451 ایران  47
    province: مرکزی ,
    type: Car,
	category: دیپلمات,   
    details: {
	firstTwoDigits: 12,
	plateCharacter: D,
	nextThreeDigits: 451,
	provinceCode: 47
    }
  }
*/

// handle motorcyles plate
Plate(12345678).info;
/*
  {
    template: 123-45678,
	province: مرکز تهران,
    type: Motorcyle,
    category: null,
    details: {
    	digits: 45678
	provinceCode:123
    }
  }
*/

Plates that have farsi digits in them(like: الف، ب، ص) will be returned in this template

  ${first_two_digits}${plate_character}${next_three_digits}ایران${province_code}
  • Checking if plate is valid
import { Plate } from "@persian-tools/persian-tools";

Plate("12D45147").isValid;
/*
  true
*/

Plate(12345678).isValid;
/*
  true
*/

Plate(1234567).isValid
/*
  will return false - plate character is not provided
*/

Plate(1204567).isValid
/*
  will return false - plate can't have 0 in its digits (except last digit)
*/

Convert Jalaali date-time into a time ago

Usage

Suppose the current time is equal to 1400/03/17 18:00:00

import { timeAgo } from "@persian-tools/persian-tools";

// Previous
timeAgo('1400/03/17 17:55:00') // 5 دقیقه قبل
timeAgo('1400/02/17 18:00:00') // حدود 1 ماه  قبل

// Next
timeAgo('1400/04/07 18:00:00') // حدود 3 هفته  بعد
timeAgo('1401/03/17 18:00:00') // حدود 1 سال  بعد

Get the Remaining Time of the Date

Usage

Takes a date(it could be string, number or date) and calculate years, months, days, hours, minutes and seconds remained to that specific date.

import { remainingTime } from "@persian-tools/persian-tools";

remainingTime("2023-05-14T13:35:59Z").toString() // ۱ سال و ۱ ماه و ۲ روز و ۳ ساعت و ۵ دقیقه و ۸ ثانیه 

const { years, months, days, hours, minutes, seconds, isFinished } = remainingTime("2023-05-14T13:35:59Z");
years // 1
minutes // 5
isFinished // false

remainingTime("2018-04-12T10:30:51Z").isFinished // true 

Validate and find information of phone number

Usage

  • Finding information such as province, type and model of phone number
import { phoneNumberDetail } from "@persian-tools/persian-tools";

phoneNumberDetail("9123456789");
/*
  {
    province: ["البرز", "زنجان", "سمنان", "قزوین", "قم", "برخی از شهرستان های استان مرکزی"],
    base: "تهران",
    operator: "همراه اول",
    type: ["permanent"],
  }
*/

phoneNumberDetail("09022002580");
/*
  {
    province: [],
    base: "کشوری",
    operator: "ایرانسل",
    type: ["permanent", "credit"],
  }
*/

phoneNumberDetail("09981000000");
/*
  {
    province: [],
    base: "کشوری",
    operator: "شاتل موبایل",
    type: ["credit"],
  }
*/
  • Validating phone number
import { phoneNumberValidator } from "@persian-tools/persian-tools";

phoneNumberValidator("09122002580"); // true
phoneNumberValidator("09192002580"); // true

phoneNumberValidator("+989022002580"); // true
phoneNumberValidator("09022002580"); // true
phoneNumberValidator("989022002580"); // true
phoneNumberValidator("00989022002580"); // true
phoneNumberValidator("9022002580"); // true

phoneNumberValidator("09802002580"); // false
  • Normalizing phone number
import { phoneNumberNormalizer } from "@persian-tools/persian-tools";

phoneNumberNormalizer("+989022002580", "0"); // 09022002580
phoneNumberNormalizer("989022002580", "0"); // 09022002580
phoneNumberNormalizer("09022002580", "0"); // 09022002580
phoneNumberNormalizer("09022002580", "+98"); // +989022002580

Todo

  • [ ] Write Jalaali and Gregorian functions to convert Date together.

Contributing

Thank you for your interest in contributing! Please feel free to put up a PR for any issue or feature request.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.

Who's using Persian tools?

If you're curious to see what can be accomplished with Persian tools, check out these apps!

If you have a software you'd like to see added, please open a pull request! All that's required is a name, link, and a PNG icon.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Supporters :open_hands:

Stargazers repo roster for @persian-tools/persian-tools