Usage Guide

Persian Tools provides a comprehensive set of utilities for Persian language processing. This guide covers the fundamental patterns and best practices for using the library.

Import Patterns

Tree-Shaking (Recommended)

Import only the utilities you need for optimal bundle size:

import { numberToWords, isPersian, addCommas } from "persian-tools";

// Usage
const persianNumber = numberToWords(1234);
const isValidPersian = isPersian("سلام دنیا");
const formattedNumber = addCommas(1234567);

Namespace Import

Import the entire library under a namespace:

import * as PersianTools from "persian-tools";

// Usage
const persianNumber = PersianTools.numberToWords(1234);
const isValidPersian = PersianTools.isPersian("سلام دنیا");

CommonJS

For Node.js environments using CommonJS:

const { numberToWords, isPersian } = require("persian-tools");

// Usage
const persianNumber = numberToWords(1234);
const isValidPersian = isPersian("سلام دنیا");

Core Patterns

Number Processing

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

// Basic conversion
numberToWords(1234); // "یک هزار و دویست و سی و چهار"

// With ordinal suffix
numberToWords(1234, { ordinal: true }); // "یک هزار و دویست و سی و چهارم"

import { wordsToNumber } from '@persian-tools/persian-tools';

// Exact matching
wordsToNumber('یک هزار و دویست و سی و چهار'); // 1234

// Fuzzy matching
wordsToNumber('یکهزار دویست سی چهار', { fuzzy: true }); // 1234

import { digitsEnToFa, digitsFaToEn } from "persian-tools";

// English to Persian digits
digitsEnToFa("1234567890"); // "۱۲۳۴۵۶۷۸۹۰"

// Persian to English digits
digitsFaToEn("۱۲۳۴۵۶۷۸۹۰"); // "1234567890"

Text Validation

import { isPersian, isArabic } from '@persian-tools/persian-tools';

// Check if text is Persian
isPersian('سلام دنیا'); // true
isPersian('Hello World'); // false

// Check if text is Arabic
isArabic('مرحبا بالعالم'); // true
isArabic('سلام دنیا'); // false

import { toPersianChars } from '@persian-tools/persian-tools';

// Convert Arabic/English chars to Persian
toPersianChars('علي'); // "علی" (Arabic ي to Persian ی)
toPersianChars('كتاب'); // "کتاب" (Arabic ك to Persian ک)

Validation

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

// Verify Iranian National ID
verifyIranianNationalId('0499370899'); // true
verifyIranianNationalId('1234567890'); // false

// Get place by National ID
getPlaceByIranNationalId('0499370899'); // { city: 'خمین', province: 'مرکزی' }

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

// Verify card number
verifyCardNumber('6274129005473742'); // true

// Get bank name
getBankNameFromCardNumber('6274129005473742'); // 'بانک پارسیان'

Configuration Options

Many utilities accept configuration objects for customized behavior:

Number Conversion Options

import { numberToWords, wordsToNumber } from "persian-tools";

// Number to words with options
numberToWords(1234, {
	ordinal: true, // Add ordinal suffix
	currency: true, // Format as currency
	scale: "short", // Use short scale
});

// Words to number with fuzzy matching
wordsToNumber("یک هزار دویست", {
	fuzzy: true, // Enable fuzzy matching
	digits: "persian", // Accept Persian digits
});

Text Processing Options

import { halfSpace, slugify } from "persian-tools";

// Half-space with custom options
halfSpace("کتاب ها", {
	cleanExtraSpaces: true,
	replaceNumbers: false,
});

// Slugify with options
slugify("عنوان مقاله ای", {
	separator: "-",
	lowercase: true,
	trim: true,
});

Error Handling

Persian Tools utilities are designed to be robust and handle edge cases gracefully:

import { numberToWords, verifyIranianNationalId } from "persian-tools";

// Utilities return sensible defaults for invalid input
numberToWords(null); // ""
numberToWords(-1); // "" (negative numbers not supported)

// Validation utilities return boolean values
verifyIranianNationalId("invalid"); // false
verifyIranianNationalId(""); // false

Performance Considerations

🚀 Lazy Loading

Import utilities individually to enable tree-shaking and reduce bundle size.

📈 Caching

For repeated operations with the same input, consider implementing your own caching layer.

⚡ Batch Processing

For processing large datasets, process items in batches to avoid blocking the main thread.

TypeScript Support

Persian Tools provides comprehensive TypeScript definitions:

import { numberToWords, NumberToWordsOptions } from "persian-tools";

// Type-safe options
const options: NumberToWordsOptions = {
	ordinal: true,
	currency: false,
};

const result: string = numberToWords(1234, options);

Introduction

Showcase

AI Agent Skills

Getting Started

Number Utilities

Validation

Text Processing

Banking

Geographic

Time Utilities

Vehicle

Usage Guide

Usage Guide

Import Patterns

Tree-Shaking (Recommended)

Namespace Import

CommonJS

Core Patterns

Number Processing

Text Validation

Validation

Configuration Options

Number Conversion Options

Text Processing Options

Error Handling

Performance Considerations

TypeScript Support

Next Steps

Examples

Number Utilities

​Usage Guide

​Import Patterns

​Tree-Shaking (Recommended)

​Namespace Import

​CommonJS

​Core Patterns

​Number Processing

​Text Validation

​Validation

​Configuration Options

​Number Conversion Options

​Text Processing Options

​Error Handling

​Performance Considerations

​TypeScript Support

​Next Steps

Examples

Number Utilities

Usage Guide

Import Patterns

Tree-Shaking (Recommended)

Namespace Import

CommonJS

Core Patterns

Number Processing

Text Validation

Validation

Configuration Options

Number Conversion Options

Text Processing Options

Error Handling

Performance Considerations

TypeScript Support

Next Steps