Skip to main content

​
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

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 }); // "یک هزار و دویست و سی و چهارم"

​
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

​
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: 'مرکزی' }

​
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

Import utilities individually to enable tree-shaking and reduce bundle size.
For repeated operations with the same input, consider implementing your own caching layer.
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);

​
Next Steps

Examples

Explore practical examples and common use cases

Number Utilities

Learn about number processing utilities