persian-tools/persian-tools

---

✨ Features

Persian Tools provides 27+ utilities for Persian language processing:

🔢 Numbers & Text

• Number Conversion: Persian words ↔ numbers with fuzzy matching
• Digit Conversion: Persian ↔ Arabic ↔ English digits
• Comma Formatting: Add/remove thousands of separators
• Ordinal Numbers: Convert to/from ordinal forms

🏛️ Validation & Verification

• National ID: Validate & generate Iranian national codes (کد ملی)
• Legal ID: Validate Iranian legal entity IDs (شناسه حقوقی)
• Phone Numbers: Validate & extract operator info
• Bank Cards: Validate & identify bank names
• Extract Card Numbers: Advanced card extraction with fuzzy matching & performance optimization
• IBAN/Sheba: Validate Iranian bank account numbers

🌍 Geographic & Location

• Place Lookup: Find city/province by national ID
• Capital Cities: Get province capitals
• Coordinates: Find province from GPS coordinates
• Vehicle Plates: Parse Iranian license plates

💰 Financial & Utilities

• Bill Calculator: Parse Iranian utility bills
• Bank Detection: Identify banks from card numbers
• IBAN Tools: Complete Iranian banking support

📝 Text Processing

• Persian Validation: Detect pure Persian text
• Character Cleanup: Remove Arabic chars from Persian
• URL Fixing: Decode Persian URLs
• Half-Space: Fix Persian typography
• Time Utilities: Persian time-ago & remaining time
• Slugify: Generate URL-safe slugs from Persian text
• Text Analysis: Comprehensive Persian text analysis

---

🚀 Quick Start

📦 Installation

# npm
npm install @persian-tools/persian-tools

# yarn  
yarn add @persian-tools/persian-tools

# pnpm
pnpm add @persian-tools/persian-tools

# bun (recommended)
bun add @persian-tools/persian-tools

💻 Usage

ES Modules (Recommended)

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

numberToWords(1234); // "یک هزار و دویست و سی و چهار"
digitsEnToFa("123"); // "۱۲۳"
verifyIranianNationalId("0499370899"); // true

CommonJS

const { numberToWords } = require('@persian-tools/persian-tools');

Browser CDN

---

🧠 AI Agent Skills

Persian Tools ships first-class Agent Skills — focused, retrievable instruction files that let Claude Code, Cursor, Copilot, and other AI coding assistants understand the library’s modules, conventions, and Persian-language nuances without you having to paste context every time.

Install the skills into your editor

# Bun
bunx skills add @persian-tools/persian-tools

# npm
npx skills add @persian-tools/persian-tools

# pnpm
pnpm dlx skills add @persian-tools/persian-tools

Each command pulls the skills/ directory into your project’s local skills folder so your AI agent retrieves them automatically when you ask about a Persian Tools utility.

---

📖 API Reference

🔢 Number Conversion

🏛️ Validation

💰 Banking & Finance

📝 Text Processing

🌍 Geographic & Utilities

---

🏗️ Development

Prerequisites

• Bun ≥ 1.3 (as runtime and package manager)

Setup

git clone https://github.com/persian-tools/persian-tools.git
cd persian-tools
bun install

Scripts

bun run build        # Build the library
bun run test         # Run tests
bun run test:watch   # Watch mode testing
bun run lint         # Lint code
bun run format       # Format code
bun run lint:fix     # Fix linting issues

Architecture

• TypeScript: Full type safety with strict mode
• Build: Unbuild (dual ESM/CJS output)
• Testing: Vitest with comprehensive coverage
• Quality: ESLint + Prettier + Husky hooks

---

🌟 Who’s Using Persian Tools?

Using Persian Tools in your project? Add it here!

---

In Memory of @mediv0 🕊️

This project is dedicated to the memory of @mediv0,
a valued contributor whose passion and work helped shape Persian Tools.
Your code lives on, and you will always be remembered in our community. ❤️

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps:

1. Install Bun (from https://bun.sh)
2. Fork & Clone the repository
3. Create a feature branch: git checkout -b my-feature
4. Make your changes with tests
5. Run bun run test and bun run lint and bun run format to ensure everything passes
6. Commit with conventional commits (e.g. feat: add new utility function)
7. Submit a pull request

---

👨‍💻 Contributors

---

📄 License

MIT License - see LICENSE for details.

---