@persian-tools/persian-tools
Advanced tools
An anthology of a variety of tools for Persian language in javascript
PersianTools is a standalone, library-agnostic JavaScript that enables some of the Persian features for use in the JavaScript.
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.
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 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
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);
Let's take a look at what an example test case would look like using Persian-tools.
| 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 |
import { wordsToNumber } from "@persian-tools/persian-tools";
wordsToNumber("منفی سه هزارمین"); // -3000
wordsToNumber("منفی سه هزارم"); // -3000
wordsToNumber("منفی سه هزار"); // -3000
wordsToNumber("سه هزار دویست و دوازده"); // 3212
wordsToNumber("دوازده هزار بیست دو"); // 12022
wordsToNumber("منفی سه هزارمین", { digits: "fa" }); // "-۳۰۰۰"
wordsToNumber("دوازده هزار بیست دو", { digits: "fa" }); // ۱۲۰۲۲
wordsToNumber("منفی سه هزارمین", { addCommas: true }); // "-3,000"
wordsToNumber("دوازده هزار بیست دو", { addCommas: true }); // "12,022"
v1.5.0):import { WordsToNumber } from "@persian-tools/persian-tools";
wordsToNumber("یگصد و بنجاه هزار", { fuzzy: true }); // "150000"
wordsToNumber("دویشت ر بیشت هزار", { fuzzy: true }); // "220000"
wordsToNumber("منقی ضد", { fuzzy: true }); // "-100"
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)
import { addCommas, removeCommas } from "@persian-tools/persian-tools";
addCommas(30000000); // "30,000,000"
removeCommas("30,000,000"); // 30000000
import {
digitsArToFa,
digitsArToEn,
digitsEnToFa,
digitsFaToEn,
digitsEnToAr,
digitsFaToAr,
} from "@persian-tools/persian-tools";
digitsArToFa("۸۹123۴۵"); // "۸۹123۴۵"
digitsArToEn("٨٩123٤٥"); // "8912345"
digitsEnToFa("123۴۵۶"); // "۱۲۳۴۵۶"
digitsEnToAr("123٤٥٦"); // "۱۲۳٤٥٦"
digitsFaToAr("۱۷۸۲۳۴۰۵۶۹"); // ١٧٨٢٣٤٠٥٦٩
import { verifyIranianNationalId, getPlaceByIranNationalId } from "@persian-tools/persian-tools";
verifyIranianNationalId("0499370899"); // true
verifyIranianNationalId("0684159415"); // false
import { verifyIranianLegalId } from "@persian-tools/persian-tools";
verifyIranianLegalId(10380285692); // false
verifyIranianLegalId(10380284790); // true
getPlaceByIranNationalId("0084575948").city; // "تهران مرکزی"
import { verifyCardNumber, getBankNameFromCardNumber } from "@persian-tools/persian-tools";
verifyCardNumber(6037701689095443); // true
getBankNameFromCardNumber("6219861034529007"); // "بانک سامان"
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.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"
| 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 }
import { isShebaValid } from "@persian-tools/persian-tools";
isShebaValid("IR820540102680020817909002"); // true
isShebaValid("IR01234567890123456789"); // false
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"
}
*/
import { halfSpace } from "@persian-tools/persian-tools";
halfSpace("نمی خواهی درخت ها را ببینیم؟"); // "نمی‌خواهی درخت‌ها را ببینیم؟"
| 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: "الف",
});
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}
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)
*/
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 سال بعد
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
Usage
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"],
}
*/
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
import { phoneNumberNormalizer } from "@persian-tools/persian-tools";
phoneNumberNormalizer("+989022002580", "0"); // 09022002580
phoneNumberNormalizer("989022002580", "0"); // 09022002580
phoneNumberNormalizer("09022002580", "0"); // 09022002580
phoneNumberNormalizer("09022002580", "+98"); // +989022002580
Usage
This function returns the Capital City name by its state name. if it can't find anything, it will throws an error.
import { findCapitalByProvince } from "@persian-tools/persian-tools";
findCapitalByProvince("خراسان رضوی"); // مشهد
findCapitalByProvince("آذربایجان شرقی"); // تبریز
// this throw an error string 'no province found'
findCapitalByProvince("دبی");
Thank you for your interest in contributing! Please feel free to put up a PR for any issue or feature request.
This project is licensed under the MIT License - see the LICENSE.md file for details.
 Bank Maskan |
 MyDong |
 Melkba |
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.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!
FAQs
An anthology of a variety of tools for Persian language in javascript
The npm package @persian-tools/persian-tools receives a total of 2,263 weekly downloads. As such, @persian-tools/persian-tools popularity was classified as popular.
We found that @persian-tools/persian-tools demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket’s threat research team has detected six malicious npm packages typosquatting popular libraries to insert SSH backdoors.
Security News
MITRE's 2024 CWE Top 25 highlights critical software vulnerabilities like XSS, SQL Injection, and CSRF, reflecting shifts due to a refined ranking methodology.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
